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The TMS320C30 Digital Signal Processor is an advanced CMOS 32-bit 
microprocessor that is optimized for signal processing applications. The 
TMS320C30 is the third generation in the Texas Instruments family of digital 
signal processors. 


The TMS320C30 is well supported by a full set of hardware and software 
development tools, including a C compiler, a full-speed in-circuit emulator, 
and a software simulator. This document discusses the software development 
tools that are included with the TMS320C30 assembly language package: 


® Assembler 

e Archiver 

@ = Linker 

@ Object format converter 


These tools can be installed on the following systems: 


® IBM-PC/PC-DOS and compatibles 
@ VAX/VMS (revisions 3.7 and up) 
Yd VAX/Ultrix 

®@ Sun-3 Workstations with UNIX 


The TMS320C30 assembly language tools create and use object files that are 
in common object file format, or COFF. COFF object files contain separate 
blocks (called sections) of code and data that you can load into different 
TMS320C30 memory spaces. You will be able to program the TMS320C30 
more efficiently if you have a basic understanding of COFF; Section 3, Intro- 
duction to Common Object File Format, discusses this object format in detail. 


Topics covered in this introductory section include: 
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Introduction - Software Development Tools Overview 


1.1 Software Development Tools Overview 


Figure 1-1 shows the TMS320C30 assembly language development flow. 
The center section of the illustration highlights the most common path; the 
other portions are optional. 
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Figure 1-1. TMS320C30 Assembly Language Development Flow 
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Introduction - Software Development Tools Overview 


@ The C compiler translates C source code into TMS320C30 assembly 
language source code. The C compiler is not included as part of the 
assembly language tools package. 


e The assembler translates assembly lJanguage source files into machine 
language object files. Source files can contain instructions, assembler 
directives, and macro directives. You can use assembler directives to 
control various aspects of the assembly process, such as the source list- 
ing format, data alignment, and section content. 


@ The linker combines object files into a single executable object module. 
As it creates the executable module, it performs relocation and resolves 
external references. The linker accepts relocatable COFF object files 
(created by the assembler) as input. It can also accept archive library 
members and output modules created by a previous linker run. Linker 
directives allow you to combine object file sections, bind sections or 
symbols to specific addresses or within memory ranges, and define or 
redefine global symbols. 


@ The archiver allows you to collect a group of files into a single archive 
library. Both the assembler and linker can use archive libraries as input. 
For example, you could collect several macros together into a macro li- 
brary; the assembler can search through a library and use the members 
that the source file calls as macros. You could use the archiver to collect 
a group of object files into an object library; the linker can link in the li- 
brary members that resolve external references. 


e The main purpose of this development process is to produce a module 
that can be executed in a system that contains a TMS320C30. You can 
use one of several debugging tools to refine and correct your code be- 
fore downloading it to a TMS320C30 system. These debugging tools 
share a common screen-oriented interface that displays and maintains 
machine status information and controls execution of the system that is 
being developed. Note that only /inked object files can be executed. 


—- The simulator is a software program that simulates TMS320C30 
functions. The simulator can execute linked COFF object modules. 
The simulator is not included with the TMS320C30 assembly lan- 
guage package. 


~ The XDS (extended development support) emulator is a realtime, 
in-circult emulator with the same screen-oriented interface as the 
software simulator. The emulator is not included with the 
TMS320C30 assembly language package. 


= The software development system (SWDS) is a PC-resident 
tool that executes code on a TMS320C30. The SWDS is not in- 
cluded with the TMS320C30 assembly language package. 


& Most EPROM programmers do not accept COFF object files as input. 
The object format converter converts a COFF object file into TI- 
tagged, Intel, or Tektronix object format. The converted file can be 
downloaded to an EPROM programmer. 
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1.2 Getting Started 
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The tools you will probably use most often are the assembler and the linker. 
This section provides a quick walkthrough so that you can get started without 
reading the whole user’s guide. These examples show the most common 
methods for invoking the assembler and linker. 


1) Create two short source files to use for the walkthrough; call them 
filea.asm and fileb.asm. 


filea.asm fileb.asm 


-file "filea" stole “fi tep™ 
-global addvec -global addvec 
vector sword 10,20,30,40 addvec LDI 0,RO 
LDI vector ,ARO RPTS o 
CALL addvec ADDI *AROQ++,RO 
RETS 


2) Assemble filea.asm; enter: 


asm30 filea 


The asm30 command invokes the assembler. filea.asm is the input 
source file. (If the input file extension ts .asm, you don’t have to specify 
the extension; the assembler uses .asm as the default.) This example 
creates an object file called filea.obj. The assembler aiways creates 
an object file. You can specify a name for the object file, but if you don’t, 
the assembler will use the input filename with an extension of .obj. 


Now assemble fileb.asm; enter: 
asm30 fileb -1 


This time, the assembler creates an object file called fileb.obj. The -| 
(lowercase "L”) option tells the assembler to create a listing file; the list- 
ing file for this example is called fileb.1st. 


3) Link filea.obj and fileb.obj; enter: 
Ink30 filea fileb -o prog.out 


The Ink30 command invokes the linker. filea.obj and fileb.obj 
are the input object files. (It the input file extension is .obj, you don’t 
have to specify the extension; the linker uses .obj as the default.) The 
linker combines filea.obj and fileb.obj to create an executable ob- 
ject module called prog.out (the -o option supplies the name of the 
output module). 


You can find more information about invoking the tools in the following sec- 
tions: 


Section Page 
4.2 Invoking the Assembler ....................::::ss:sssssnseensscesseesesssessessessnesenereeeres 4-3 
8.2 HIVOKING the ATCNIVEN 2ainiiasicicrcecsacaatetsicncepenceateetaneaulepa near aa piceenst 8-3 
9.2 INVOKING: THO INK Gl faci cccciccroecccnenanconccssceemad nese cin baecneulacataeiauae ener 9-3 
10.2. Invoking the Object Format Converter ..............cccccecccceeeeeeeeerereeeeeenes 10-3 
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1.3 Manual Organization 


Section 1 


Section 2 


Section 3 


Section 4 


Section 5 


Section 6 


Section 7 


Section 8 


Section 9 


Section 10 


Appendix A 


Appendix B 


Appendix C 
Appendix D 


Appendix E 


Appendix F 


Introduction 

Provides an overview of the assembly language tools and the assembly lan- 
guage development process, gives quick examples for invoking the tools, lists 
related documentation, and explains the style and symbol conventions used 
throughout this document. 


Software Installation 
Contains instructions for installing the assembly language tools on VAX/VMS, 
VAX/Ultrix, Sun-3/UNIX, and IBM-PC/PC-DOS systems. 


Introduction to Common Object File Format 

Discusses the basic COFF concept of sections and how they can help you 
to use the assembler and linker more efficiently. Read Section 3 before using 
the assembler and linker. 


Assembler Description 
Tells you how to invoke the assembler and discusses source statement format, 
valid constants and expressions, and assembler output. 


Assembler Directives 
Divided into two parts; the first part describes the directives according to 
function, and the second part is an alphabetical reference. 


Instruction Set Summary 
Summarizes the TMS320C30 instruction set alphabetically and by function; 
also summarizes addressing modes and optional syntax forms. 


Macro Language 
Describes macro directives and macro creation. 


Archiver Description 
Contains instructions for invoking the archiver, creating new archive libraries, 
and modifying existing libraries. 


Linker Description 
Tells you how to invoke the linker, provides details of linker operation, dis- 
cusses linker directives, and presents a detailed linking example. 


Object Format Converter Description 
Telis you how to invoke the object format converter so that you can convert a 
COFF object file into an Intel, Tektronix, or Tl-tagged object format. 


Common Object File Format 
Contains specific information about the internal format of COFF object files. 


Symbolic Debugging Directives 
Lists the symbolic debugging directives that theTMS320C30 C compiler uses. 


Assembler Error Messages 
Linker Error Messages 
List the assembler and linker error messages. 


ASCIil Character Set 
Provides a table of the ASCII character set. 


Glossary 
Defines a glossary of terms and acronyms used in this book. 
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1.4 Related Documentation 
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The following TMS320C30 documents are available from Texas Instruments: 


The 7MS320 Family Development Support Reference Guide 
(literature number SPRUO11) describes the wide range of TMS320 
products that are available. 


Details on Signal Processing is a quarterly newsletter that provides 
information about new TMS320 family products, new documentation, 
development too! updates, and similar information. If you would like 
your name added to the newsletter mailing list, call the Texas Instru- 
ments Customer Response Center (1-800-232-3200). 


The Third-Generation TMS320 User's Guide (literature number 
SPRUOQ31) discusses hardware and _ software aspects of the 
TMS320C30, such as pin functions, architecture, and interfaces, and 
contains the TMS320C30 instruction set. 


The TMS320C30 C Compiler Reference Guide (literature number 
SPRUO34) tells you how to use the TMS320C30 C compiler. This C 
compiler accepts standard Kernighan and Ritchie C source code and 
produces TMS320C30 assembly language source code. We suggest 
that you use 7he C Programming Language (written by Brian W. Ker- 
nighan and Dennis M. Ritchie, published by Prentice-Hall) as a com- 
panion to the 7MS320C30 C Compiler Reference Guide. 
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1.5 Style and Symbol Conventions 


In this document program listings, program examples, screen displays, 
filenames, and symbol names are shown in a special font. Examples 
use a bold version of the special font for emphasis. Here is 
a sample program listing: 


0011 0005 oOoo1 .field ly 2 
0012 90005 0003 .field 3. 4 
0013 0005 0006 -field 6, 3 
0014 0006 .even 


In a syntax description, the instruction, command, or directive is in a 


bold face font and parameters are in /ta/ics. Portions of a syntax that 
are in bold face should be entered as shown; portions of a syntax that 
are in ftalics describe the type of information that should be entered. 
Here is an example of a directive syntax: 


-asect “section name”, address 


.asect is the directive. This directive has two parameters, indicated by 
section name and address. When you use .asect, the first parameter must 
be an actual section name, enclosed in double quotes; the second pa- 
rameter must be an address. 


Square brackets ( [ anc | ) indicate an optional parameter. For example, 
the asm30 command has several optional parameters: 


asm30_ = /input file [object file [listing file]]] [-options] 


= The first parameter, input file, is optional. 

= The second parameter, object file, is optional; in addition, you can 
specify an object fife only if you also specified an /nput file. 

The third parameter, /isting file, is optional; in addition, you can 
specify a /isting file only if you also specified an input fife and an 
object file. 

= The fourth parameter, -options, is optional; you can specify options 
even if you specified no other parameters. 


Square brackets are also used as part of the pathname specification for 
VMS pathnames; in this case, the brackets are actually part of the path- 
name (‘they aren’t optional). 


Braces ( { and } ) indicate a list. The | symbol (read as or) separates 
items within a list. Here’s an example of a list: 


Ce Sees) 
This list provides three choices: *, *+, or *-. 


Some directives can have a varying number of parameters. For example, 
the .byte directive can have up to 100 parameters. The syntax for this 
directive is: 


byte va/ue; [,..., valué,] 


This syntax shows that .byte must have at least one value parameter, but 
you have the option of supplying additional value parameters, separated 
by commas. 
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Section 2 


Software Installation 


This section contains step-by-step instructions for installing the assembler, 
archiver, linker, and object format converter. This software can be installed 
on the following systems: 


@ DEC VAX/VMS' 
@ IBM-PC with PC-DOS2 (versions 2.1 and up) and compatibles 


@ UNIX? Systems 


- VAX/Ultrix 
_ SUN-3 


You will find installation. instructions for these systems in the following sec- 
tions: 


Section Page 
ZV installation VO PCS: gecnc vote vat ac ogtaceetatees antes yoacen Rs aencetuSeteteeed nau 2-2 
2.2 Installation for VAX/V MS sivccecccscxcesdcatescsevesseacactessazeccaecaiouassuaestensdarcias 2-3 
2.3 Installation for UNIX SySteM .........ccccecececcccccceceesseeceesseresecssceuseneeaaees 2-4 


Section 1.5 (page 1-7) lists style and symbol conventions that are used in this 
section. 


VAX and VMS are trademarks of Digital Equipment Corporation. 
PC-DOS is a trademark of International Business Machines. 


UNIX is a registered trademark of AT&T. 


Software Installation - PCs 


2.1 
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installation for PCs 


The TMS320C30 software package is shipped on two double-sided, dou- 
ble-density diskettes. The disk labelled ASM/LINK/ARCH contains the as- 
sembler, linker, and archiver. The disk labelled ROM/DEMO contains the 
object format converter. The toals execute in batch mode. At least 512K bytes 
of memory space must be available in your system. 


These instructions are for both hard disk systems and dual floppy drive svs- 
tems. On a dual-drive system, the PC-DOS system diskette should be in drive 
B. The instructions use these symbols for drive names: 


A: 


3) 


Floppy disk drive for hard disk systems or source drive for dual-drive 
systems. 


Destination or system disk drive for dual-drive systems. 
Winchester (hard disk) for hard disk systems. | 


Make backups of the product diskettes. 
Create a directory to contain the TMS320C30 software. 


@ On hard disk systems, enter. MD C:\C30TOOLS 


@ On dual/-drive systems, enter: MD B:\C30TOOLS 
Copy the TMS320C30 tools onto the hard disk or the system disk. 


& On hard disk systems, enter: COPY A:\*.* C:\C30TOOLS\*.* 


8 On dual-drive systems, enter: COPY A:\*.* B:\C30TOOLS\*.* 


Software Installation - VAX/VMS Systems 


2.2 Installation for VAX/VMS 


The TMS320C30 software tape was created with the VMS BACKUP utility at 
1600 BPI. These tools were developed on version 4.5 of VMS. If you are 
using an earlier version of VMS, you may need to relink the object files; refer 
to the Release Notes for relinking instructions. 


1) 
2) 


3) 


Mount the tape on your tape drive. 


Execute the following VMS commands. Note that you must create a 
destination directory for the tools; in this example, DEST: directory 
represents that directory. Replace TAPE with the name of the tape drive 
you are using. 


S$ allocate TAPE: 

$ init/den=1600 TAPE:C30 

$ mount/for/den=1600 TAPE: 

$ backup TAPE:ASM30.bck DEST[:directory] 
$ dismount TAPE: 

$ dealloc TAPE: 


The product tape contains a file called setup.com. This file sets up 
VMS symbols that allow you to execute the tools in the same manner 
as other VMS commands. Enter the following command to execute the 
file: 


$ @setup DEST: directory 


This sets up symbols that you can use to call the various tools. As the 
file is executed, it will display the defined symbols on the screen. 


You may want to include the commands from setup.com in your 
login.com file. This automatically defines symbols for running the 
tools each time you log in. 
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Software Installation - UNIX Systems 


2.3 Installation for UNIX Systems — 
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The TMS320C30 product tape was made at 1600 BPI using Zar utility. Follow 
these instructions to install the assembly language tools package: 


1) Mount the tape on your tape drive. 


2) Make sure that the directory that you'll store the tools in is thé current 
directory: 


3) Enter the tar command for your system; for example, 
tar x 


This copies the entire tape into the directory. 


Section 3 


Introduction to Common Object File Format 


The assembier and linker create object files that can be executed by the 
TMS320C30. The format that these object files are in is called common object 
file format, or COFF. 


COFF object format makes modular programming easier because it encourages 
you to think in terms of b/ocks of code and data when you write an assembly 
language program. These blocks are known as sections. Both the assembler 
and the linker provide directives that allow you to create and manipulate sec- 


tions. 

This chapter provides an overview of COFF sections and includes the follow- 

ing topics: 

Section Page 
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3.2 How the Assembler Handles Sections ............cccccscsseseesseeeereeeeseeteeeenes 3-3 
3.3 How the Linker Handles Sections .0.............cccccceceeeeeeeeeeeneeseseeeeeeneeeenns 3-9 
S24: “RELOCATION eae ctestaces cence ce cooeeasetote eet shia chloe cisco sided uicatuts 3-14 
S.5: OddING a PIOGlAN: cciciesztccereuthe cused isececd se deeateentaes . auceees: 3-15 
3.0: “SVMbDOIS Ia CORP: File ciincsiicassxssnaussecessagesescarronaaaeausnentednanse 3-16 


Appendix A details COFF object structure; for example, it describes the fields 
in a file header and the structure of a symbol table entry. Appendix A is mainly 
useful for those of you who are interested in the internal format of object files. 


Common Object File Format - Sections 


3.1 Sections 


3-2 


The smallest relocatable unit of an object file is called a section. A section 
is a relocatable block of code or data which will (ultimately) occupy contig- 
uous space in TMS320C30 memory. Each section of an object file is separate 
and distinct from the other sections. COFF object files always contain three 
default sections: 


e The .text section usually contains executable code. 
@ The .data section usually contains initialized data. 
®@ The .bss section usually reserves space for uninitialized variables. 


In addition, the assembler and linker allow you to create, name, and link 
named sections that can be used similarly to the .data, .text, and .bss sections. 


It is important to note that there are two basic types of sections: 


@ Initialized sections contain data or code. The .text and .data sections 
are initialized; named sections created with the .sect and .asect assem- 
bler directives are also initialized. 


@ Uninitialized sections reserve space in the memory map for uninitial- 
ized data. The .bss section is uninitialized; named sections created with 
the .usect assembler directive are also uninitialized. 


The assembler provides several directives that allow you to associate various 
portions of code and data with the appropriate sections. The assembler builds 
these sections during the assembly process, creating an object file that is or- 
ganized similarly to the object file shown in Figure 3-1. 


One of the linker’s functions is to relocate sections into the target memory map 
(this is called allocation). Since most systems contain several different types 
of memory, using sections can help you to use target memory more efficiently. 
All sections are independently relocatable; you can place different sections 
into various blocks of target memory. For example, you can define a section 
that contains an initialization routine, and then allocate the routine into the 
portion of the memory map that contains EPROM. 


Figure 3-1 shows the relationship between sections in an object file and a 
hypothetical target memory. 


Object File Target Memory 


= 0 


Figure 3-1. Partitioning Memory into Logical Blocks 


Introduction to COFF - How the Assembler Handles Sections 


3.2 How the Assembler Handles Sections 


The assembler’s main function in regard to sections is to identify the portions 
of an assembly language program that belong in a particular section. The as- 
sembler has six directives that support this function: 


e The .bss and .usect directives reserve defined amounts of space in 
memory (usually RAM). This reserved space is used for storing vari- 
ables. 


@ The .text directive identifies the source statements that follow it as 
executable code. The statements following a .text directive are assem- 
bled into the .text section. 


@ The .data directive identifies the source statements that follow it as 
initialized data. The statements following a .data directive are assembled 
into the .data section. 


@ The .sect and .asect directives define named sections that can be 
used like the .text and .data sections. The .sect directive creates a section 
with relocatable addresses; the .asect directive creates a section with 
absolute addresses. The statements following a .sect or .asect directive 
are assembled into the appropriate named section. 


The .bss and .usect directives create uninitialized sections, the .text, .data, 
sect, and .asect directives create initialized sections. 


Note: 


If you don’t use any of the sections directives, the assembler assembles 
everything into the .text section. 


3.2.1 Uninitialized Sections 


Uninitialized sections reserve space in TMS320C30 memory; they are usually 
allocated into RAM. These sections have no actual contents in the object file; 
they simply reserve memory. A program can use this space at run time for 
creating and storing variables. 


Uninitialized data areas are built by using the .bss and .usect assembler direc- 
tives. The .bss directive reserves space in the .bss section. The .usect directive 
reserves space in a specific uninitialized, named section. Each time you invoke 
the .bss directive, the assembler reserves more space in the .bss section. Each 
time you invoke the .usect directive, the assembler reserves more space in the 
specified named section. 


You will usually allocate all variables into the .bss section. Occasionally, you 
may find it convenient to reserve additional space for variables and allocate 
this space separately from .bss; you can use .usect for this purpose. 


The syntaxes for these directives are: 


-bss = symbol, size in words 
symbol .usect “section name", size in words 
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®@ The symbo/ points to the first word reserved by this invocation of the 
.bss or .usect directive. The symbo/ corresponds to the name of the 
variable that you’re reserving space for. It can be referenced by any other 
section and can also be declared as a global symbol (with the .global 
assembler directive). 


e The size is an absolute expression. The .bss directive reserves s/ze words 
in the .bss section; the .usect directive reserves size words in section 
name. | 


® The section name parameter tells the assembler which named section to 
reserve space in. (For more information about named sections, see 
Section 3.2.3.) 


The .text, .data, .sect, and .asect directives tell the assembler to stop assembl- 
ing into the current section and begin assembling into the indicated section. 
The .bss and .usect directives, however, do not end the current section and 
begin a new one; they simply “escape” from the current section temporarily. 
The .bss and .usect directives can appear anywhere in an initialized section 
without affecting the contents of the initialized section. 


3.2.2 Initialized Sections 
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Initialized sections contain executable code or initialized data. The contents 
of these sections are stored in the object file and placed in TMS320C30 me- 
mory when the program is loaded. Each initialized section is separately relo- 
catable and may reference symbols that are defined in other sections. The 
linker automatically resolves these section-relative references. 


Four directives tell the assembler to place code or data into a section. The 
syntaxes for these directives are: 


text 

.data 

sect “section name” 

easect “section name", address 


When the assembler encounters one of these directives, it stops assembling 
into the current section (acting as an implied “end current section” command). 
It then assembles subsequent code into the respective section until it en- 
counters a .text, .data, .asect, or .sect directive. 


Sections are built up through an iterative process. For example, when the 
assembler first encounters a .data directive, the .data section is empty. The 
statements following this first .data directive are assembled into the .data 
section (until the assembler encounters a .text, .sect, or .asect directive). If the 
assembler encounters subsequent .data directives, it adds the statements fol- 
lowing these .data directives to the statements that are already in the .data 
section. This creates a single .data section that can be allocated contiguously 
into memory. | 
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3.2.3 Named Sections 


Named sections are sections that you create. You can use them like the de- 
fault .text, .data, and .bss sections, but they are assembled separately from the 
default sections. 


For example, repeated use of the .text directive builds up a single .text section 
in the object file. When linked, this .text section is allocated into memory as 
a single unit. Suppose there is a portion of executable code (perhaps an in- 
itialization routine) that you don’t want allocated with .text. If you assemble 
this segment of code into a named section, it is assembled separately from 
text, and you will be able to allocate it into memory separately from .text. 
(Note that you can also assemble initialized data that is separate from the .data 
section, and you can reserve space for uninitialized variables that is separate 
from the .bss section.) 


Three directives let you create named sections: 


® The .usect directive creates sections that are used like the .bss seciion. 
These sections reserve space in RAM for variables. 


© The .sect and .asect directives create sections that can be used like the 
default .text and .data sections. The .sect directive creates named sec- 
tions with re/ocatab/e addresses; the .asect directive creates named sec- 
tions with abso/ute addresses. 


The syntaxes for these directives are: 


symbol .usect “section name”, size in words 
sect “section name” 
-asect "section name”, address 


The section name parameter is the name of the section. Section names are 
significant to 8 characters. You can create up to 32,767 separate named sec- 
tions. 


Each time you invoke one of these directives with a new name, you create a 
new named section. Each time you invoke one of these directives with a name 
that was already used, the assembler assembles code or data (or reserves 
space) into the section with that name. You cannot use the same names with 
different directives. That is, you cannot create a section with the .usect di- 
rective and then try to use the same section with .sect. 
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3.2.4 Section Program Counters 


The assembler maintains a separate program counter for each section. These 
program counters are known as section program counters, or SPCs. 


An SPC represents the current address within a section of code or data. Ini- 
tially, the assembler sets each SPC to 0. As the assembler fills a section with 
code and data, it increments the appropriate SPC. If you resume assembling 
into a section, the assembler remembers the appropriate SPC’s previous value 
and continues incrementing at that point. 


The assembler treats each section as if it begins at address 0; the linker reio- 
cates each section according to its final location in the memory map. 


3.2.5 Absolute Sections 


The .asect directive defines a named section whose addresses are absolute 
with respect to a specified address. Absolute sections are useful for loading 
code from off-chip memory into faster on-chip memory. 


The syntax for this directive is: 
.asect “section name", address 


The section name parameter identifies the name of the absolute section (Sec- 
tion 3.2.3 describes named sections). The address parameter identifies the 
section’s absolute starting address in target memory. In order to use an ab- 
solute section, you must know which location you want the section to execute 
from, and specify it as the address parameter. 


Most sections directives create sections with relocatable addresses. These 
sections always have an initial SPC value of 0; the linker relocates these sec- 
tions appropriately. The initial SPC value for an absolute section, however, is 
the specified address. The addresses of all code assembled into an absolute 
section are offsets from this address. The linker does relocate sections defined 
with .asect; however, any labels defined within an absolute section retain their 
absolute (runtime) addresses. Thus, references to these labels refer to their 
runtime addresses, even though the section is not initially loaded at this ad- 
dress. 


3.2.6 An Example That Uses Sections Directives 


3-6 


Figure 3-2 shows how you can build COFF sections incrementally, using the 
sections directives to swap back and forth between the different sections. You 
can use sections directives: 


® To begin assembling code or data into a section for the first time, or 


@ To continue assembling into a section that already contains code. !n this 
case, the assembler simply appends the new code to the code that is 
already assembled into the section. 


The format of this example is a listing file. By using a listing file, this example 
shows how the SPCs are modified during assembly. A line in a listing file has 
four fields: 


f 
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0001. 
0002 
0003 
0004 
0005 


0006 
0007 
0008 
0009 
0010 
OO11 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
0020 
0021 
0022 
0023 
0024 
0025 
0026 
0027 
0028 
0029 
0030 
0031 
0032 
0033 


0034 
0035 
0036 
0037 
0038 
0039 
0040 
0041 
0042 
0043 
0044 
0045 
0046 
0047 
0048 
0049 
0050 
0051 
0052 
0053 
0054 
0055 


000000 
000000 
OO0001 
000002 


000000 
000001 


000003 


000000 
000000 
OO00001 
000002 
000002 
000003 
000004 


000004 
000004 
000005 
000006 


000000 
QOO0001 


000005 
000005 
000006 
000007 
000007 
000008 
000009 


000000 
000000 
OO00001 


OOOQ00011 
00000022 
00000033 


00000123 


O869000A 
08610000 


02412001 
CE46OFFFE 
15210000+ 


QOOQOOAA 
OOOOOOBB 
O00000CC 


O8609000A 
08610000 


OAC12001 
6E46FFFE 
L521 0007+ 


OOO000000' 
00000005! 


KRREAKKEKEKKEKEKEKKEKEKEKRKEKRKEKRKERRERKRRERKEKREERKREKRKKREKKREESE 


** Assemble an initialized table into .data ** 
KERR RRR RRR RRR RRR RRR EK 
-data 


coeff .word Olin, O22, -033h 


RREKEKKKEEKRKEKEKREKEKKER KEKE KRKEKRKREKERRERKKKRKKEKEKRKEKRKRKREEK 


** Reserve space in .bss for two variables ** 
KRREKEKRKRKERKEKEKRKKERER KEKE KEKE RKEKEKRREEREKRREKKRKEREREER 


.bss varl,l 


.bss buffer, 10 


KEKE KKEKEKEKEKKEKKERKEKKEREKEKREKRKKEKREKEKREKRKEKEKRERKEKKEKK 


** Still in .data * 
KKEKKKKKKKRKEKKEK KKK KERR RE KKRARKAKKKKRKRKR RRR KKK KRRAK 
PEE .word 0123h 
KEKE KEE KKK KERR RREKRREKRRKRKRRERKER 
xk Assemble code into the .text section ** 
KEK KKKRKEKKKE KEKE KERR KKK RRR 
-text 
add: LDI 10,AR1 
LDI 0), Rab: 
aloop: 
ADDI *ARO++,R1 
DBNZ AR1,aloop 
STI R1,@varl 
KRREKKRKEK KKK RRR EI 
**k* Assemble another initialized table into x 
**k the .data section x 
KRREKRKRKEKRKKEREKRKEKR EK KE KR KEKE RRR KR KERR KKK 
.data 
ivals -word OAAh, OBBh, OCCh 


KRERKRKRKRKKEEKKEKKEEKEKRRRKEKEKRRERRKRKRKEEKKKEREKRKEKRKRKKEEE 


*k Define another section for more variables ** 
KKK RRR RRR KEKE RRR KR KKK RRR KE 


var2 -usect "newvars",1 
inbuf -pSsect “"newvars",7 


REKEKEKREKERERKRRERERERKRKEEKRKRERRERRERERERKREREREERERKEEER 


*k* Assemble more code into .text xk 
KR KERR RRR RE REKKE KR RKR RRR RKRRKRKRKRRRKER KKK E HK 


~text 
mpy: LDt 10,AR1 
LDI 0O,R1 
mloop: 
MPYI *ARO++,R1 
DBNZ AR1,mloop 
STI R1,@var2 


KRKKEKEKKEKEKKEKKEKEKEKRKKREKEKREKKEKREKEKEEKREKRKEKRKKEKRRKRKKRKEEEE 


** Define a named section for int. vectors x 
KKRKEKKKKKKRKKEKRKRRKREKR KKK KEK KKK KRRKKKKKKRR RK KR KIRK 


FSECE "vectors" 
.-word add, mpy 


Figure 3-2. Using Sections Directives 
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As Figure 3-3 shows, the file in Figure 3-2 creates five sections: 


text contains 10 words of object code. 
.data contains 7 words of object code. 


vectors is a named section created with the .sect directive; it contains 2 
words of initialized data. 


.bss reserves 11 words in memory. 


newvars is a named section created with the .usect directive; it reserves 8 
words in memory. 


The second column identifies the object code that is assembled into these 
sections; the first column identifies the source statements that generated the 
object code. 


Line Numbers Object Code 
text section 


12,13 


newvars 


43,44 


Figure 3-3. Object Code Generated by Figure 3-2 
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3.3 How the Linker Handles Sections 


The linker has two main functions in regard to sections. First, the linker uses 
the sections in COFF object files as building blocks; it combines input sections 
(when more than one file is being linked) to create output sections in an ex- 
ecutable COFF output module. Second, the linker chooses memory addresses 
for the output sections. 


The linker provides two directives that support these functions: 


@ The MEMORY directive allows you to define the memory map of a tar- 
get system. You can name portions of memory and specify their starting 
addresses and their lengths. 


e The SECTIONS directive tells the linker how to combine input sections 
and where to place the output sections in memory. 


It is not always necessary to use linker directives. If you don’t use them, the 
linker uses the default allocation algorithm described in Section 3.3.1. When 
you do use linker directives, you must specify them in a linker command file. 


Refer to the following sections for more information about linker command 
files and linker directives: 


Section Page 
94. Linker Command Files: shen. sdncdariceteien eased eee 9-11 
9:6- “ThE: MEMORY DIreCtive: sxccectcrditen cet ciedivenadiccix neat edeadeiaseianendiodey. 9-14 
9:7 “The: SECTIONS: DireG tive esdscite cdi cstonsscianodesa dices te cseds accuses daations 9-16 


3.3.1 Default Allocation 


You can link files without specifying a MEMORY or SECTIONS directive. The 
linker uses a default model to combine sections (if necessary) and allocate 
them into memory. When using the default model, the linker: 


1) Assumes that memory begins at address Oh. 

2) Assumes that 2“* words are available to allocate object code into. 

3)  Allocates the .text section into memory, beginning at address 0. 

4)  Allocates the .data section into memory, immediately following .text. 

5)  Allocates the .bss section into memory, immediately following .data. 

6)  Allocates a// named sections into memory, immediately following .bss. 
Named sections are allocated in the order that they’re encountered in the 
input files. 


Note that the linker does not actually place an object code into memory; it 
assigns addresses to sections so that a /oader can place the code in memory. 


Figure 3-4 shows how a Sing/e file would be allocated using default allo- 
cation. 


3-9 | 
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Object Code Memory 
Qo0000h 
text 
size = 10 words 
QOOOOAh 
.data 
size = 7 words 
000011h 
vectors size = 11 words 
00001Ch 
.Oss 
size = 8 words 
newvars 000024h 


size = 2 words 


Figure 3-4. Placing the Object Code from Figure 3-2 into Memory 


(Default Allocation) 


As Figure 3-4 shows, the linker: 


1) 
2) 
3) 


4) 


5) 


Allocates the .text section first, beginning at address Oh. The .text sec- 
tion contains 10 words of object code. 


Allocates the .data section next, beginning at address Ah. The .data 
section contains 7 words of object code. 


Allocates the .bss section third, beginning at address 11h. The .bss 
section reserves 11 words in memory. 


Allocates the named section newvars at address 1Ch. (newvars was 
the first named section encountered in the original input file - see Figure 
3-2.) The newvars section reserves 8 words in memory. 


Allocates the named section vectors at address 24h. The vectors 
section contains 2 words of object code. 


Figure 3-5 shows a simple example of how two files might be linked together. 
When you link several files using the default algorithm, the linker combines 
all input sections that have the same name into one output section that has 
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this same name. For exampie, the linker combines the .text sections from two 
input files to create one .text output section. 


file1.obj 


Memory 


file2.obj 


Figure 3-5. Combining Input Sections from Two Files (Default Allocation) 


In Figure 3-5, filel.obj and file2.obj each contain the .text, .data, and 
.bss default sections and a named section called vars; file2.obj also con- 
tains a named section called Init. As Figure 3-5 shows, the linker: 


1) 


2) 


3) 


4) 


5) 


Combines filel .text with file2 .text to form one .text output section. 
The .text output section is allocated at address Oh. 


Combines filel .data with file2 .data to form the .data output sec- 
tion. The .data output section is allocated following the .text output 
section. 


Combines filel .bss with file2 .bss to form the .bss output section. 
The .bss output section is allocated following the .data output section. 


Combines filel vars with file2 vars to form the vars output sec- 
tion. (The vars section is the first named section that is encountered 
during the link, so it is allocated before the second named section, 
Init.) The vars output section is allocated following the .bss output 
section. 


Allocates the Init section from file2 after the vars section. 
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3.3.2 Placing Sections in the Memory Map 


Figure 3-4 and Figure 3-5 illustrate the linker’s default methods for combining 
sections and allocating them into memory. Sometimes you may not want to 
use the default setup. For example, you may not want to combine all of the 
.text sections into a single .text section. Or, you might want a named section 
placed at address 40h instead of the .text section. Most memory maps are 
comprised of various types of memories (DRAM, ROM, EPROM, etc.) in var- 
ying amounts; you may want to place a section in a particular type of memory. 


The next two illustrations show another possible combination of the sections 
from Figure 3-4 


Figure 3-6 contains MEMORY and SECTIONS definitions. 


Figure 3-7 shows how the sections from figure Figure 3-6 are allocated 
into memory. 
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/* Linker command file ae 4 
PP RTE ARR IR OP ee Po ST See Ae Le AS ee Tee Ne ee 


MEMORY 
{ 


OO0000h length 
OO00040h length 
801000h length 
801400h length 


VECS: origin 
ROM: origin 
RAMO: origin 
RAM1: origin 


Hou we Wl 


Hou ne a 


} 


SECTIONS 
{ 


vectors oo00000h 
cert 

-data 

.bss 

newvars 


Figure 3-6. MEMORY and SECTIONS Directives for Figure 3-7 


The MEMORY directive in Figure 3-6 defines four memory ranges: 


— VECS 
‘= ROM 
= RAMO 
a RAM1 


The origin for each of these ranges identifies the range’s starting address 
in memory. The /ength specifies the length of the range. For example, 
memory range RAMO, with starting address 801000h and length 400h, 
defines the addresses 801000h through 8013FFh in memory. 
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© The SECTIONS directive in Figure 3-6 defines the order in which the 
sections are allocated into memory. The vectors section must begin 
at address 0. Both .text and .data are allocated into the ROM area that 
was defined by the MEMORY directive. The .bss section is allocated 
into RAMO, and newvars is allocated into RAM1. 


Memory 


000000h 
(interrupt vectors) 


o00002h 


000040h 
(internal ROM) 


OO0004Ah 


data 


0000s th 


801000h 
(RAM blockO) 


vectors 


801400h 
(RAM block‘) 


801408h 
801800h 


newvars 


Figure 3-7. Rearranging the Memory Map from Figure 3-4 


Introduction to COFF - Relocation 


3.4 Relocation 


The assembler treats each section as if it began at address 0. All relocatable 
symbols (labels) are relative to address 0 in their sections. Of course, ali sec- 
tions can’t actually begin at address 0 in memory, so the linker relocates 
sections by: 


@ Allocating sections in the memory map so that they begin at the appro- 
priate address, 


@ Adjusting symbol values to correspond to the new section addresses, 
and 


@ Patching references to relocated symbols to reflect the adjusted symbol 
values. 


The linker uses re/ocation entries to adjust references to symbol values. The 
assembler creates a relocation entry each time a relocatable symbol is refer- 
enced. The linker then uses these entries to patch the references after the 
symbols are relocated. Figure 3-8 contains a code segment that generates 
relocation entries. 


X 
00000000 
00000000 600000000! X ; Generates a relocation entry 


O0000001 082000002+ @Y,RO ; Generates a relocation entry 
00000002 O60000000_ Y: 


Figure 3-8. An Example of Code that Generates Relocation Entries 


In Figure 3-8, both the symbols X and Y are relocatable. <X is defined in some 
other module; y is defined in the .text section of this module. When assem- 
bled, X has a value of 0 (the assembler assumes all undefined external symbols 
have values of 0) and Y has a value of 2 (relative to address O in the .text 
section). The assembler generates two relocation entries, one for X and one 
for y. The reference to X is an external reference (indicated by the ! character 
in the listing). The reference to Y is to an internally defined relocatable symbol 
(indicated by +). 


After linking, suppose that X is relocated to address 100h. Suppose also that 
the .text section is relocated to begin at address 200h; y now has a relocated 
value of 202h. The linker uses the two relocation entries to patch the two 
references in the object code: 


60000000 BR X becomes 60000100 
08200002 LDI @Y,RO becomes 08200202 


Each section in a COFF object file has a table of relocation entries. The table 
contains one relocation entry for each relocatable reference in the section. The 
linker usually removes relocation entries after it uses them. This prevents the 
output file from being relocated again (if it is relinked or when it is loaded). 
A file that contains no relocation entries is an abso/ute file (all its addresses 
are absolute addresses). If you want the linker to retain relocation entries, 
invoke the linker with the -r option. 
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3.5 Loading a Program 


The linker produces executable COFF object modules. An executable object 
file has the same COFF format as object files that are used as linker input; 
however, the sections in an executable object file are combined and relocated 
to fit into target memory. 


In order to run a program, the data in the executable object module must be 
transferred (or loaded) into target system memory. 


Several methods can be used for loading a program, depending on the exe- 
cution environment. Some of the more common situations are listed below. 


The TMS320C30 debugging tools (including the software simulator, 
XDS emulator, and software development system) have built-in loaders. 
Each of these tools has a LOAD command that invokes a COFF loader; 
the loader reads the executable file and copies the program into target 
memory. 


If you are using a ROM- or EPROM -based system, you can use the ob- 
ject format converter (which is included with the assembly language 
package) to convert the executable COFF object module into one of 
several object file formats. You can then use the converted file with an 
EPROM programmer to burn the program into an EPROM. 


Some TMS320C30 programs are loaded under the control of an operat- 
ing system or monitor software running directly on the target system. 
In this type of application, the target system usually has an interface to 
the file system on which the executable module is stored. You must 
write a custom loader for this type of system. The loader must compre- 
hend the file system (in order to access the file) as well as the memory 
organization of the target system (to load the program into memory). 
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3.6 Symbols in a COFF File 


A COFF file contains a symbol table that stores information about symbols in 
the program. The linker uses this table when it performs relocation. Debug- 
ging tools can also use the symbol table to provide symbolic debugging. 


3.6.1 External Symbols 


External symbols are symbols which are defined in one module and referenced 
in another module. You can use the .global directive to identify symbols as 
external. In a source module, an external symbol can be either: 


@ Defined in the current module, or 
@ Defined in another module and referenced in the current module. 


The following code segment illustrates these definitions. 


xs LDI RO,R1 > Define x 
LDI @y,RO ; Reference y 
-global x ; DEF of x 
-gJlobal y ; REF of y 


The .global definition of x says that it is.an external symbol! defined in this 
module, and that other modules can reference x. The .global definition of y 
says that it is an undefined symbol that is defined in some other module. 


The assembler places both x and y in the object file’s symbol table. When the 
file is linked with other object files, the entry for x defines unresolved refer- 
ences to x from other files. The entry for y causes the linker to look through 
the symbol tables of other files to look for y’s definition. 


The linker must match all references with corresponding definitions. If the 
linker cannot find a symbol’s definition, it prints an error message about the 
unresolved reference. This type of error prevents the linker from creating an 
executable object module. 


3.6.2 The Symbol Table 


The assembler always generates an entry in the symbol table when it en- 
counters an external symbol (both definitions and references). The assembler 
also creates special symbols that point to the beginning of each section; the 
linker uses these symbols to ‘relocate references to other symbols in a section. 


The assembler does not usually create symbol table entries for any other type 
of symbol because the linker does not use them. For example, labels are not 
included in the symbol table unless they are declared with .global. For sym- 
bolic debugging purposes, it is sometimes useful to have entries in the symbol 
table for each symbol in a program. To accomplish this, invoke the assembler 
with the -s option. 


Section 4 


Assembler Description 


The assembler translates assembly language source files into machine lan- 
guage object files. These object files are in common object file format 
(COFF), discussed in Section 3. Source files can contain these assembly 
language elements: 


Assembler directives (described in Section 5), 
Assembly language instructions (Summarized in Section 6), and 
Macro directives (described in Section 7). 


The assembler: 


e Is a two-pass assembler. 

@ Processes the source statements in a text file to produce a relocatable 
object file. 

e Produces a source listing (if requested) and provides you with conirol 
over this listing. 

e Appends a cross-reference listing to the source listing (if requested). 

@ Allows you to segment your code into sections. 

® Maintains an SPC (section program counter) for each section of object 
code. 

@ Defines and references global symbols. 

@ Assembles conditional blocks. 

e Supports macros, allowing you to define macros inline or in a macro li- 
brary. 
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4.1 Assembler Development Flow 


Figure 4-1 illustrates the assembler’s role in the assembly language develop- 
ment flow. The assembler accepts assembly language source files as input and 
creates a COFF object file that can be linked. 
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Y) 
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Figure 4-1. Assembler Development Flow 
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4.2 Invoking the Assembler 


To invoke the assembler, enter: 


asm30 [input file [object file [listing file]/]] [-options] 


input file 


object file 


listing file 


option 


names the assembler source file. If you do not supply an ex- 
tension, the assembler assumes that the input file has the de- 
fault extension .asm. {If you do not supply an input filename 
when you invoke the assembler, the assembler will prompt you 
for one. 


names the object file that the assembler creates. If you do not 
supply an extension, the assembler uses .ob/ as a default ex- 
tension. If you do not supply an object filename the assembler 
creates a file that uses the input filename with the .ob/ exten- 
sion. 


names the optional listing file that the assembler can create. If 
you do not supply a name for a listing file, the assembler does 
not create one, unless you use the -! (lowercase "“L”) option. 
In this case, the assembler uses the input filename with the ./st 
extension. if you supply a filename without an extension, the 
assembler uses ./st. 


identifies the assembler options that you want to use. Case is 
insignificant for assembler options. Options can appear any- 
where on the command line; precede each option with a hy- 
phen (-). You can string the options together; for example, -Ic 
is equivalent to -I -c. Valid options include: 


-1 (lowercase “L”) produces a listing file. 


-i specifies a directory where the assembler can find files 
named by the .copy, .include, or .mlib directives. The format 
of the -i option is -tgathname. You can specify up to 10 
directories in this manner; each pathname must be preceded 
by the -i option. 


-x produces a cross-reference table and appends it to the end 
of the listing file. If you use -x but do not request a listing 
file, the assembler creates one anyway, but the listing con- 
tains only the cross-reference table. 


-s puts all defined symbols in the object file’s symboi! table. 
Usually, the assembler puts only global symbols into the 
symbol table. When you use -s, symbols that are defined 
as labels or as assembly-time constants are also placed in 
the symbol table. 


-c makes case insignificant. For example, the symbois ABC 
and abc will be equivalent. /f you do not use this option, 
case is significant. 


-q (quiet) suppresses the banner and all progress information. 
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4.3 Specifying Alternate Directories for Assembler Input 


4.3.1 


4-4 


The .copy and .include directives tell the assembler to read source statements 
from another file; the .mlib directive names a library that contains macro defi- 
nitions. Section 5, Assembler Directives, provides examples of the .copy, .in- 
clude, and .mlib directives. The syntax for these directives is: 


copy “filename” 
include “fi/ename” 
.mlib “filename” 


The filename names a copy/include file that the assembler reads statements 
from or a macro library that contains macro definitions. The filename can be 
a complete pathname or a filename with no path information. If you provide 
a pathname, the assembler uses that path and does not /ook for the file in any 
other directories. If you do not provide path information, the assembler 
searches for the file in: 


1) The directory that contains the current source file. (The current source 
file refers to the file that is being assembled when the .copy, .inciude, or 
.mlib directive is encountered.) 


2) Any directories named with the -i assembler option. 
3) Any directories set with the environment variable A—DIR. 


You can augment the assembler’s directory search algorithm by using the -! 
assembler option or the environment variables A—DIR. 


-i Assembler Option 


The assembler option names an alternate directory that contains copy/include 
files or macro libraries. The format of the -i option is: 


asm30 -ipathname source filename 


You can use up to 10 -i options per invocation; each -i option names one 
pathname. \|n assembly source, you can now use the .copy, .include, or .mlib 
directive without specifying any path information. If the assembler doesn’t 
find the file in the directory that contains the current source file, it searches the 
paths provided by the -i options. 


For example, assume that a file called source.asm is in the current directory; 
source.asm contains the following directive statement: 


-copy "copy.asm". 


The complete path/filename for copy. asm is: 


@ c:\c30\files\copy.asm (DOS), 
@ [c30.files]copy.asm (VMS), or 
@ /c30/files/copy.asm(UNIX). 


This is how you invoke the assembler: 


DOS: asm30 -ic:\c30\files source.asm 
VMS: asm30 -i[c30.files] source.asm 
UNIX: asm30 -i/c30/files source.asm 
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The assembler first searches for copy.asm in the current directory, because 
source.asm is tn the current directory. Then, the assembler searches in the 
directory named with the -! option. 


4.3.2 Environment Variable (A—DIR) 


An environment variable is a system symbol that you define and assign a String 
to. The assembler uses an environment variable named A—DIR to name al- 
ternate directories that contain copy/include files or macro libraries. The 
command for assigning the environment variable is: 


DOS: set A—DIR=pathname;another pathname ... 
VMS: assign A—DIR “pathname,another pathname ... 
UNIX: setenv A—DIR “pathname;another pathname ... 


uw 


uw 


The pathnames are directories that contain copy/include files or macro li- 
braries. You can separate the pathnames with a semicolon or with blanks. In 
assembly source, you can now use the .copy, .include, or .mlib directive 
without specifying any path information. If the assembler doesn’t find the file 
in the directory that contains the current source file or in directories named 
by -1, it searches the paths named by the environment variable. 


For example, assume that a file called source. asm contains these statements: 


-copy "copyl.asm" 
copy "copy2.asm" 


Assume that the complete path and file information for these copy files ts: 


@ c:\320\files\copyl.asm and c:\dsys\copy2.asm (DOS), 
e [320.files]copyl.asm and [dsys]copy2.asm (VMS), or 
@ /320/files/copl.asm and /dsys/cop2.asm (UNIX) 


This is how you set the environment variables and invoke the assembler: 


DOS: set A-DIR=c:\dsys; c:\exec\files 
asm30 -ic:\320\files source.asm 


VMS: assign A-DIR "[dsys]; [exec.files]" 
asm30 -i[320.files] source.asm 


UNIX: setenv A_DIR "/exec/files;/dsys" 
asm30 -1/320/files source.asm 


The assembler first searches for copyl.asmand copy2.asm in the current di- 
rectory, because source.asm Is in the current directory. Then the assembler 
searches in the directory named with the icon -i option, and finds copyl.asm. 
Finally, the assembler searches the directory named with A—DIR and finds 
copy2.asm. 


Note that the environment variable remains set until you reboot the system or 
reset the variable by entering: 


DOS: set A_DIR= 
VMS: deassignA-DIR 
UNIX: setenv A_DIR" " 
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4.4 Source Statement Format 


TMS320C30 assembly language source programs consist of source state- 
ments that can contain assembier directives, assembly language instructions, 
macro directives, and comments. Source statement lines can be as long as the 
source file format allows. The assembler reads up to 200 characters per line. 
If the statement contains more than 200 characters, the assembler truncates 
the line and issues a warning. 


The next several lines show examples of source statements: 


SYM -set OA5h ; Symbol SYM = OA5Sh 
Begin: ADDI SYM+5,R1 ; Add (SYM+5) to the contents of Rl 
LDI R1,R2 ; Move contents of R1 to R2 


A source statement can contain four ordered fields. The general syntax for 
source statements Is: 


[label[:]] mnemonic foperand list] [;comment] 


where 


6 Statements must begin with a label, a blank, an asterisk, or a semicolon. 
e Labels are optional; if used, they must begin in column 1. 


e One or more blanks must separate each field. (Note that tab characters 
are equivalent to blanks.) 


@ Comments are optional. Comments that begin in column 1 can begin 
with an asterisk or a semicolon (* or ;), but comments that begin in any 
other column must begin with a semicolon. 


4.4.1 Label Field 


Labels are optional for all assembly language instructions and for most (but 
not all) assembler directives. A label must begin in column 1 of a source 
statement. A label can contain up to 32 alphanumeric characters (A~-Z, a~-z, 
0-9, —, and $). Labels are case sensitive, and the first character cannot be a 
number. A label can be followed by a colon (:); the colon is not treated as 
part of the label name. If you don’t use a label, then the first character position 
must contain a blank, a semicolon, or an asterisk. 


When you use a label, its value is the current value of the section program 
counter (the label points to the statement it’s associated with). If, for example, 
you use the .word directive to initialize several words, a label would point to 
the first word. In the following example, the label Start has the value 3Fh. 


0002 * Assume some other code was assembled 
0003 OOOO3F OQOOOOOOOA Start: -word OAh; 3,7 

000040 00000003 

000041 00000007 
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A label on a line by itself is a valid statement. It assigns the current value of 
the section program counter to the label - this is equivalent to the following 
directive statement: 


label -set S$ ; (S$ represents the current value of the SPC) 


When a labei appears on a line by itself, it points to the instruction on the next 
line (the SPC is not incremented): 


0005 000042 Here: 
0006 000042 08010000 LDI RO,R1 


4.4.2 Mnemonic Field 


The mnemonic field follows the label field. 7he mnemonic field cannot start 
in column 7, or it would be interpreted as a label. The mnemonic field can 
contain one of the following opcodes: 


® Machine-instruction mnemonic (such as ADDI, MPYF, LDI) 


@ Assembler directive (such as .data, .list, .set) 
@ Macro directive (such as SMACRO, SLOOP, SENDLOOP) 
@ 


A macro invocation 


4.4.3 Operand Field 


The operand field is a list of operands that follows the mnemonic field. An 
operand can be a constant (see Section 4.5), a symbol (see Section 4.7), or 
a combination of constants and symbols in an expression (see Section 4.8). 
You must separate operands with commas. 


4.4.4 Comment Field 


A comment can begin in any column and extends to the end of the source line. 
A comment can contain any ASCII character including a blank. Comments 
are printed in the assembly source listing but they do not affect the assembly. 


A source statement that contains only a comment is valid. If it begins in col- 
umn 1, it can start with a; ora *. Comments that begin anywhere else on the 
line must begin with a;. The * symbol designates a comment only if it ap- 
pears in column 1. 
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4.5 Constants 


The assembler supports seven types of constants: 


Binary integer constants, 

Octal integer constants, 
Decimal integer constants, 
Hexadecimal integer constants, 
Floating-point constants, 
Character constants, and 
Assembiy-time constants. 


The assembler maintains each constant internally as a 32-bit quantity. 
Note that constants are not sign extended. For example, the constant 
OFFFFH is equal to OOOOFFFF 46 or 65,5354; it does not equal -1. 

4.5.1 Binary Integers 


A binary integer constant is a string of up to 32 binary digits (Os and 1s) fol- 
lowed by the suffix B (or b). If less than 32 digits are specified, the assembler 
right-justifies the value and zero-fills the unspecified bits. Examples of valid 
binary constants include: 


OOO00000B Constant equal to 019 or 046 
0100000b = Constant equal to 3239 or 2046 
O1b Constant equal to 149 or 116 
11111000B Constant equal to 24819 or OF846 


4.5.2 Octal Integers 


An octal integer constant is a string of up to 11 octal digits (O through 7) 
followed by the suffix Q (or q). Examples of valid octal constants include: 


100 Constant equal to 819 or 846 
1000000 Constant equal to 32,7689 or 8000416 
2260 Constant equal to 15049 or 9646 
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4.5.3 Decimal Integers 


A decimal integer constant is a string of decimal digits ranging from 
-2,147,483,647 to 4,294,967,295. Examples of valid decimal constants in- 


clude: 

1000 Constant equal to 100019 or 3E81¢ 
-32768 Constant equal to -32,76819 or -80001¢ 
25 Constant equal to 2519 or 1946 


4.5.4 Hexadecimal Integers 


A hexadecimal integer constant is a string of up to eight hexadecimal digits 
followed by the suffix H (or h). Hexadecimal digits include the decimal values 
0-9 and the !etters A-F and a-f. A hexadecimal constant must begin with a 
decimal value (0-9). \f less than eight hexadecimal digits are specified, the 
assembler right-justifies the bits. Examples of valid hexadecimal constants 


include: 

78h Constant equal to 12019 or 0078146 
OFh Constant equal to 1519 or OOOF1¢ 
37ACH Constant equal to 14,2529 or 37AC1¢ 


4.5.5 Character Constants 


A character constant is a string of one to four characters enclosed in single 
quotes. The characters are represented internally as 8-bit ASCII characters. 
Two consecutive single quotes are required to represent each single quote 
within a character constant. A character constant consisting only of two sin- 
gle quotes (no letter) is valid and is assigned the value O. If less than four 
characters are specified, the assembler right-justifies the bits. Examples of 
valid character constants include: 


‘ab’ Represented internally as 0000626146 
‘CS’ Represented internally as 0000004356 
fad 2 Represented internally as 0000442746 
‘abcd’ Represented internally as 6463626146, 


Note the difference between character constants and character strings (Sec- 
tion 4.6 discusses character strings). A character constant represents a single 
integer value; a string is a list of characters. 
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4.5.6 Floating-Point Constants 


A floating-point constant is a string of decimal digits, followed by an optional 
decimal point, fractional portion. and exponent portion. The syntax for a 
floating-point number is: 


{ +{- ] [~[ nnn J] . { nnn [ Efe { +{- ] nnn j} J] 


where nnn is a string of decimal digits. A floating-point constant may be 
preceded with a + ora -. You must specify a decimal point; for example, 3.e5 
is valid, but 3e5 is illegal. The exponent indicates a power of 10. 


Valid floating-point constants include: 


3 

3.14 

3 
-0.3146e13 
+314.59e-2 


Floating-point constants cannot be used in expressions; the only valid 
floating-point operations are unary + and -. Floating-point constants that are 
used in instructions are represented in short format (16 bits). All other float- 
ing-point constants are represented in single-precision format (32 bits). 


For more information about floating-point format, refer to the 7hird-Genera- 
tion TMS320 User's Guide. 


4.5.7  Assembly-Time Constants 


lf you use the .set directive to assign a constant value to a symbol, the symbol 
becomes an assembly-time constant. In order to use this constant in ex- 
pressions, the value that is assigned to it must be absolute. For example: 


sym set 3 
LDL sym,RO ; Load the constant 3 into RO 


If you assign a floating-point constant to a symbol, then the symbol can be 
used only as a floating-point constant. Similarly, if you assign an integer 
constant to a symbol, then the symbol can be used only as an integer constant. 
The following example is ///ega/: 


sym ser 3 ; Integer constant 
LDF sym,RO ; Invalid - floating-point 
; constant required 


You can also use the .set directive to assign symbolic constants for register 
names. In this case, the symbol becomes a synonym for the register: 


sym .set RO 
LDI 10,sym 
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4.6 Character Strings 


A character string is a string of characters enclosed in doub/e quotes. Double 
quotes within character strings are represented by two consecutive double 
quotes. The maximum string length varies — it is defined for each directive that 
requires a character string. Characters are represented internally as 8-bit ASCII 
characters. Appendix E lists valid characters. 


Examples of valid character strings include: 
“sample program” Defines a 14-character string, sample program 
“PLAN ""C""" Defines an 8-character string, PLAN "C" 


Character strings are used for: 


@ Filenames (as in .copy "filename") 
e Section names (as in .sect "section name") 
@ Data initialization directives (as in .byte "charstring" ) 


4.7 Symbols 


Symbols are used as labels and in operands. A symbol name is a string of up 
to 32 alphanumeric characters (A-Z, a-z, 0-9, $, and —). The first character in 
a symbol cannot be a number; symbols cannot contain embedded blanks. The 
symbols you define are case sensitive; for example, the assembler will recog- 
nize ABC, Abc, and abc as three unique symbols. (You can override this with 
the -c assembler option.) This type of symbol is valid only during the assem- 
bly in which it is defined, unless you use the .global directive to declare it as 
an external symbol. 


Symbols that are used as labels become symbolic addresses that are associ- 
ated with locations in the program. Labels must be unique; do not re-use 
them for other statements. Mnemonic opcodes and assembler directive names 
(without the *.” prefix) are valid label names. 


Symbols that are used in operands must be defined in the assembly by ap- 
pearing as labels or as operands of a .global, .set, or .bss directive. 


The assembler has several predefined symbols, including: 


@ $ (the dollar sign character), which represents the current value of the 
section program counter (SPC). 


@ These register symbols: 


ARO-AR7 IF IRO RE RO-R7 
BK IE IR1 RC SP 
DP lOF PC RS ST 
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4.8 Expressions 


An expression is a constant, a symbol, or a series of constants and symbols 
separated by arithmetic operators. The range of valid expression values is 
-2,147,483,647 to 4,294,967,295. 


Three main factors influence the order of expression evaluation: 


@ Parentheses. Expressions that are enclosed in parentheses are always 
evaluated first. 


Example: 3/(4/2) = 4, but 8/4/2 = 1 


@ Precedence groups. Operators (listed in Table 4-1) are divided into 
four precedence groups. When the order of expression evaluation is not 
determined by parentheses, the highest-precedence operation is evalu- 
ated first. 


Example: 8 + 4/2 = 10 (4/2 is evaluated first) 


@ Left-to-right evaluation. When parentheses and precedence groups 
do not determine the order of expression evaluation, the expressions are 
evaluated from left to right. (Note that the highest-precedence group is 
evaluated from right to left.) 


Example: 8/4*2 = 4, but 8/(4*2) = 1 


Note that all expressions are represented internally as 32-bit values. For ex- 
ample, -2 is represented as FFFF FFFEh, not as FFFEh. 


4.8.1 Operators 


Table 4-1 lists the operators that can be used in expressions. They are listed 
according to precedence group. 


Table 4-1. Operators 


Group 1 (Highest Precedence) Group 3 | | 
Right-to-Left Evaluation Left-to-Right Evaluation | 


Unary plus (positive expression) Addition 

Unary minus (negative expression) Subtraction 

(COM) 1s complement : | (OR) Bitwise OR 

(NOT) Logical NOT (if expr. = O, 1 (XOR) Bitwise exclusive OR 
is returned, else O is returned) Bitwise AND 


Group 2 Group 4 (Relational Operators) | 
Left-to-Right Evaluation Left-to-Right Evaluation 


= Multiplication | Less than 
Division . | Greater than 
(MOD) Modulo Less than or equai to 
(SHL) Shift left Greater than or equal to 
(SHR) Shift right Equal to (= = 

Not equal to 


cp o> + 


Note: Operators in parentheses indicate an alternate form. 
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4.8.2 Expression Overflow or Underflow 


The assembler checks for overflow and underflow conditions when arithmetic 
cperations are performed at assembly time. The assembler issues a Value 
Truncated warning whenever an overflow or underflow occurs. The assem- 
bler does not check for overflow cr underflow in multiplication. 


4.8.3 VWell-Defined Expressions 


Some assembler directives require well-defined expressions as operands. 
Well-defined expressions contain only symbols or assembly-time constants 
that are defined before they are encountered in the expression. The evaluation 
of a weil-defined expression must be absolute. An example of a well-defined 
expression is: 


LOOOh+X Where X was previously defined as an absciute symbol. 


oe Conditional Expressions 


The assembler supports relational operators that can be used in any ex- 
pression; they are especially useful for conditional assembiy. Relational oper- 
ators include: 


= Equa i= Not equal 
== Equa! < Less than 
<= Less than cr equal > Greater than 
>= Greater than or equa! 


4.8.0 Relocatable Symbo!s and Legal Expressions 


Tabie 4-2 summarizes valid operations on absolute, relocatable, and external 
symbols. An expression cannot multiply or divide by a relocatable or external 
symbol. An expression cannot coniain unrescived symbois that are relocata- 
ble with respect to different sections. 


Table 4-2. Exoressions with Absolute and Relocatabie Symbois 
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Here are some examples of expressions that use absolute and relocatable 
symbols. These examples use four symbols that are defined in the same sec- 


tion: 


intern_l: 
LABI: 
intern—2: 


-global extern_1 ; Defined in an external module 
.word pial 8 ; Relocatable, defined in current module 
.Set 2 ; LAB1 = 2 

; Relocatable, defined in current module 
Example 1: 


The statements in this example use an absolute symbol, LAB1. The first 
statement puts the value 51 into register ARO. The second statement 
loads the value 27 into register ARO. 


LDi LAB1 + ((4+3) * 7), ARO ; ARO = 51 
LDL LAB1 + 4 + 3 * 7, ARO ; ARO = 27 
Exampie 2: 


All legal expressions can be reduced to one of two forms: 
relocatable symbol + absolute symbol 
or 
absolute value 


Unary operators can only be applied to absolute values; they cannot be 
applied to relocatable symbols. Expressions that cannot be reduced to 
contain only one relocatable symbol are illegal. The first statement in tne 
following example is legal; the statements that follow it are not. 


LDI extern—1 - 10, ARO Legal 
LDI i0-extern—1, ARO Can't negate reloc. symbol 


LDI extern—1/10, ARO f/ isn't an additive operator 


LDI -(intern—1), ARO : Can't negate reloc. symbol 
LDI intern—1 + extern_1, ARO ; Multiple relocatables 


Example 3: 


The first statement below is legal; although intern—1 and intern—2 
are relocatable, their difference is absolute because they’re in the same 
section. Subtracting one relocatable symbol from another reduces the 
expression to re/ocatable symbol + absolute value. The second state- 
ment is illegal because the sum of two relocatable symbols is not an 
absolute value. 


LDI intern_1 - intern-2 + extern—1,ARO0 ; Legal 
LDI intern—1l + intern—2 + extern —1,ARO0 ; Illegal 
Example 4: 


An external symbol’s placement in an expression is important to ex- 
pression evaluation. Although the statement below is similar to the first 
statement in the previous example, it is illegal. This is because of left- 
to-right operator precedence; the assembler attempts to add intern—1 
to extern—l. 


LDI intern—1 + extern—2 - intern—2, ARO ; Illegal 
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4.9 Source Listings 


A source listing shows source statements and the object code they produce. 
To obtain a listing file, invoke the assembler with the -| (lowercase ”L”) op- 
tion. 


At the top of each source listing page are two banner fines, a blank line, and 
a title line. Any title supplied by a .title directive is printed on this line; a page 
number is printed to the right of the title. If you don’t use the .title directive, 
the title area is left blank. The assembler inserts a blank line below the title 
line. 


Each line in the source file produces a line in the listing file that contains a 
source statement number, an SPC value, the object code assembled, and the 
source statement. A source statement may produce more than one word of 
object code. The assembler lists the SPC value and object code on a separate 
line for each additional word. Each additional line is listed immediately fol- 
lowing the source statement line. 


1 2 3 4 

0027 000006 O3F20018 Begin: ASH 24,R2 ; shift to top of word 
0028 000007 02000002 ADDI R2,RO ; add to LSBs 

0029 000008 78800000 RETS 


Field 1 Source Statement Number. The source statement number is a 
4-digit decimal number. The assembler numbers source lines as it 
encounters them in the source file; some statements increment the 
line counter but are not listed (for example, .title statements and 
statements following a .nolist are not listed). The difference be- 
tween two consecutive source line numbers indicates the number 
of statements in the source file that are not listed. Source lines 
generated by a macro call, a .copy directive, or an .include directive 
are renumbered starting at 0001. The original sequence continues 
after the copying or macro expansion is complete. The assembler 
precedes the line numbers of copied files with a letter code to 
identify the level of copying. An A indicates the first level, B indi- 
cates a second level, etc. 


Field 2 Section Program Counter. This field contains the section program 
counter, or SPC, value (hexadecimal). Each section (.text, .data, 
.bss, and named sections) maintains a separate SPC. Some direc- 
tives do not affect the SPC; they leave this field blank. 


Field 3. Object Code. This field contains the hexadecimal representation of 
the object code. All machine instructions and directives use this 
field to list object code. This field also indicates the relocation type 
by appending one of the following characters to the end of the field: 


{ Undefined external reference 

” Relocatable with respect to the .text section 
Data relocatable (.data, .sect) 

+ .bss relocatable 


ue 
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Field 4 Source Statement Field. This field contains the characters of the 
source statement as they were scanned by the assembler. 


TMS320C30 Assembler 


(c) 


maximum line length accepted by the assembler is 200 characters. 
Spacing in this field is determined by the spacing in the source 


statement. 


Version 1.0 87.100 


TMS320C30 Integer Multiply 


| 0002 
| 0003 

0004 
| 0005 
| 0006 
| 0007 
| 0008 

0009 

0010 
} OO11 
| 0012 
| 0013 
} 0014 

0015 
| 0016 

0017 
| 0018 
} 0019 
| 0020 
| 0021 

0022 

0023 
| 0024 

0025 
| 0026 
| 0027 
| 0028 
| 0029 
| 0030 


000000 
000000 


O00001 
000002 
000003 
000004 
000005 


000006 
000007 
000008 


| No Errors, 


C20100C0 


O3EOFFES8 
O3E1FFES8 
OACOQOOO1 
QAC1COO00 
880800C0 


O03E20018 


02000002 
78800000 


No Warn 


Copyright 1987, Texas Instruments Inc. 


Fri May 29 14:13:54 1987 


PAGE 1 


KRKEKRKEKRKRERRREKERKERKRKRRERRKEKERERKRRRERRERERRRERERERKRKRKRK KKK: 


A 


ARO points to 2 words of temporary memory 


result = (x0 * y) 
KEKKEREKERKKEREKKRKEKEKKRKREKEERE 


-global mpy32 


Sit 
| | STI 
ASH 
ASH 
MPYT 
MPYI 
MPYT 
| | ADDI 
ASH 
ADDI 
RETS 
-end 


ings 


RO, *ARO 

R1, *+ARO 
-24,R0 

-24,R1 
*+ARO,RO 
*ARO,R1 
*ARO,*+ARO,RO 
RO,R1,R2 
24,R2 

R2,ROQO 


Let xO = 8 MSBs of x, 


+ 
* 


ue NO NS NS NO HO NO WE NO NO 


( 
K* 


yO = 8 MSBs of y 


* TMS320C30 32x32 Integer Multiply 
* 

vg Inputs: x in RO, y in R 
* 

* 

id OULHUtS s “x Fy In RO 

* 

. Operation: 

* 

* 

* 

* 


yO © x as 
KAKKKKKK KEK REE K KEKE K KKK 


save x 

save y 

xO into RO 

yO into R1 

mpy upper bytes: x0 * y 
yO * x 

mpy lower words 

add product MSBs 

shift back to top of word 

add to LSBs 


Figure 4-2. Sample Assembler Listing 


The 
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4.70 Cross-Reference Listings 


A cross-reference listing shows symbols and their definitions. Teo cbtain a 
cross-reference listing, invoke the assembler with the -x option cr use the 
option directive. The assembler will append the cross-reference to the end 
of the source listing. 


—_ 


TMS320C30 Assembler Version 1.0 87.100 Fri May 29 14:13:54 1987 | 


labelO 
labell 


(c) Copyright 1987, Texas Instruments Inc. 
PAGE 3 

VALUE DEEN REF 

OCOOAABB 0007 0041 

OOAABBCC 0008 0049 

AABBCCDD 0009 GO5.7 

OOOQOQOAA 0006 SiO Me 

E5541885 0010 0065 

REF OO11 0026 0034 0042 0050 
GOSS OO 72 

OO000002+ 0019 0028 0036 0044 0052 0060 
0074 

00000003! 0028 0027 0035 0043 O051 0059 
0073 

eA 


Figure 4-3. Cross-Reference Listing Format 


The label column contains each symbol! that was defined or referenced 
during the assembly. 


The value column contains a 4-digit hexadecimal number which is the 
value assigned to the symbol or a name that describes the symbol’s at- 
tributes. A value may also be followed by a character that describes the 
symbol’s attributes. Table 4-3 lists these characters and names. 


The definition (DEFN) column contains the statement number that 
defines the symbol. This column is blank for undefined symbols. 


The reference (REF) column lists the line numbers of statements that 
reference the symbol. A blank in this column indicates that the symbol 
was never used. 


Table 4-3. Symbol Attributes for Cross-Reference Listings 


era [eine 
| orName | Meaning | 
[ner [eternal reference (global symbol) 
|__| Symbol dsfined ina tet action | 
ee 
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Assembler Directives 


Assembler directives supply program data and control the assembly process. 
Assembler directives allow you to: 


®@ Reserve space in memory for uninitialized variables 
Control the appearance of listings 

Initialize memory 

Assemble conditional blocks 

Define global variables 

Specify libraries that the assembler can obtain macros from 
Examine symbolic debugging information 


This section is divided into two parts: the first part (Sections 5-1 through 
5-7) describes the directives according to function, and the second part 
(Section 5.8) is an alphabetical reference. You will find the following topics 
in this section: 


Section Page 
Bt DITECH VES OUIMMANY Ass teitescatcteces tadeceseiceiec cuit aie eee hanes oo 5-2 
52 -SECUONS: DILCCUVES® siacsscnss ieee mavanaci vo venanseas eis ashonsaui 6 reawengwse aceeeecesaes 5-4 
5.3 Directives that Initialize M@MOSY ............cccccsseeeeeeeeeeeeeeeseeeeseneesaeaeees 5-6 
5.4 Directives that Align the Section Program Counter ...............000068 5-9 
5.5 Directives that Format the Output Listing .................ccccccseeeceeeeeeeeeee 5-10 
5.6 Conditional Assembly Directives ...............ccccecesssseeeeeeeseceseeeeeeeesseeees 5-11 
5.7 Directives that Reference Other Files ...............cccccsssseecceessseeeeeeneeeeens 5-12 
5.0: Directives: Reference «ti cccscsciccectakcese is hci cnanncioseodrteannserredaaiinies 5-13 


The TMS320C30 C compiler uses several directives for symbolic debugging. 
Unlike other directives, symbolic debugging directives are not used in most 
assembly language programs. Appendix B discusses these directives; they are 
not discussed in this section. 


Assembler Directives - Directives Summary 


5.1 Directives Summary 


Table 5-1 summarizes the assembler directives. Mote that a//l source state- 
ments that contain a directive may have a label and a comment. To improve 
readability, they are not shown as part of the directives’ syntax. 


Table 5-1. Directives Summary 


sections Directives 
Minemonic and Synta i | Description 


RAAT ACRES ST NSTOR CID 


asect “section name”, address | Assemble into an absoiute named (initialized) | 
| section 


.oss symbol, size in words | Reserve size words in the .bss (uninitialized data) | 
section 
| .data | Assemble into the data (initialized data) | se ection 


SILI I. ad: FRE DY 


Jabel “svmbal” | Define a label in an absolute section : 
etal cata cement eh AAC rk EE 


225A CNC a A I ALAA RAO CIV RISES EIEN SEAR TOR GOI AS CIS IORI RES TTS HIE ITE RAE OTE TEES OTE ITO T Oe SO RO TIT 


Assemble into a named (initialized) section 
Assemble into the -text (executable code) section 


ST VT NUMAN 


sect “section name” 


MATE SLCC A 2 ERMA AA Cl AT TALI SARI TORE OSSIAN ENE SIE ATL BISNIS ENTE TOTTI PBT 


Franc DOR 7 Sete crea AREY MORALS O RIS 


ee usect "section name” , siz e in words Reserve size words in a named (uninitialized) 


section 
Directives that initialize Memory 


ESSN ORE DL NER EAE LIISA SAIS AL ETON PRI ERE TET TIT TK RETR EUR EET MG EAD 


Kinemonic and Syntax 


ESCA a MLAS RCI 8? 


Description 


! Initialize one or more successive bytes i in the cur- | 
| rent section 


| field value [size in bits] | Initialize a variable-length field di 
float valued [..... Valuép] Initialize one or more 32-bit, single- precision, | 
| floating-point constants ane — | 

hword values [, joer value} : i initialize one or more 16-bit (half- -word) values 1 

j int values /...., value) | initialize one or more 32-bit intege rs | 
jslong valves [...., valuen] | initialize one or more 32-bit integers | 

| symbol set valued initialize an assembly-time constant 
| space sizeinwards | Reserve size words in the current saction | 
_string “stings” [... "stringn"] it Initialize one or more text strings 
word valués [... ~ valuép/ es mented tnacsen tl initialize one or more 32- -bit int tegers 
| «Directives that Align the Section Program Counter (SPC) i 
1 Vinemonic ee Description 


remo enenns IEE ITE SS RU DLE AON 6 A AREER OSTREAM TAN 


| .align Align the S SPC on as 32-word {cache} boundary | 


ened HA ROUEN 2A AT aN WOE CIRC STAPF ERA 6 PES ONC AIS AESOP ARATE AA SEA EAN 


ven Align the e SPC. ona word boundary 


{AAAS ASAI RFPASSRAE A AON CT CORRS YRS ARRAY RS 223) RAHA RATS AK OTIS SSE SA CA OTE VAS LE PTO NBA REPRO ANETTA PI AO STATES MEA TORI ET INSIDE IIT SEO BEE, I BEANS BY 


Directives that Format ‘the Output Listing 
ceed abun Mc ac BGRt Oth oe Sasi el oN NN SRS A ao Ae — 


Mnemonic and Syntax I Description | 


AIRRSEMCEAN WIRES LEASED EINE BEN PFT TEVA SICAL MELEE TSR AAU NOTIN SIA RYT 


ADIEU SS AEA EAR IOLA ABN AT 


MAB ADE oD FMI IN NG SEIT UAT SIT AP A A BA ENS SAM HVA RL AF TERRA IER BAPE AI SEIN MRE a BoP AIPA WT NS SLANE LIS TREAT RT OO | 5 SIO RAST BAO LAE EP TI ENR IA LAS LAE MAE LS AY Ne SAREE RRMA ER id TOE UACSTIAT ES 4 
Jength page fength Set the page lenath of the source fisting | 
rar aniaatererreat pe ULAR I og MD REI SEAL I BIAT AT Nid MATA Lu! 1d SURI Lat TORN TA MS, IN RIA SLE LS I IOTS LIL VE SIT ICE LER IAT PNY FESO CLE SIL IS ARG ESL NTT font Sieinanabennenteaidle. Sees _ outa PLM L ADA SUEZ SORE LLM TINT EIA AOE ANE AI: prasmmnacconanoimecnccsisass 
Hist Restart the source tisting 
ia se ar a AE i cen Nath et RR OES OE ae Oe OO 
se 
F Preeist Allow macro listings (default) 
| easiakosbt-nad atten esereae een tee seemen Orr ae Menem pcaeee ere nana tcl ahaha Dieta. Ra DEEN EE 
‘ Oe aw, * { ¥ 
b PMPORSE > inhib macro stings 
[tmaecnss onc MARR tem wi ASSESS TN at seen EPR ET RE ae eae “ies See corona cram 
; _ a 
Siang the source HST rt ' 
Eicetsoniinitbesiin 2c sorte neta etieaeben ai Se ine aay aetiologies cme pat Hc tc asineeriae ramen comorimponi arses 


Assembler Directives —- Directives Summary 


Table 5-1. Directives Summary (Concluded) 


Directives that Format the Output Listing (continued) 


Mnemonic and syntax cescription ; 
| option {BID|F/L|MITIX} —_ | Select output listing options | -_ 
_page | Se | Fiect a page in the source listing 
title ’ string” —_ oe Print a title in source page heading 


width page width | | Set the page width of the source listing 


Conditional Assembly Directi ves 


Manemonic and Syntax | Description | 

i expression | | Begin conditional assembly | 
| else | | ‘Optional conditional assembly | 
! endif | a | | | Enc conditional assembly | ae 
[ | in Directives that Reference Other Files 
ae ivinemonic and Syntax | Description a 
| ‘coy ["]filenamel”] ase | Z nclude source > statements from another file 
cet symbol] [4 SY¥NBOlp] | iden tify one or more symbols that are defined in a 
| the current module and used in other modules | 
|_giok sai symboly {,... _symboln] - identify one or more global (external) symbols 
Ancit CHL ‘ae. ["Jflename["]_ | | include source statements from another file | | 
| mii [” jfil [" ]filename!{” ] ee ee tee ; Specify the name of a macro library 7 
| ef eee yon _symboln] ~~: ] Identify one or mcre symbols that are used in the 
| current module but defined in another module 


_Misceflaneous Directives 


| 


Vinemonic and Syntax 


ESA RT ES AA AMO 


Description 


7 ae NOD HELI A LT ATO 


2 


Program end 


a) 
ae 
om 


ce 


Patt Symbolic Debugging Directivest | 
i Mnemonic and Syntax | Description 

Po Sa ac mR aa —— | 
, sock Seginning fine number Begin a C block 
Aces i ak Gas Ss Sc nS Ss RO lcs tient ae be vassal ne asa 5 tn eg ci a ge ct (in secisiiaraeeteiadll 


4 4 
; .encojock ending line number cad a a C bieck 
ending line numbe End a fi netion definiti 
i 3s ending line number ad a function definition 
SESAIE ADI at ere IRs En cA COED A RO RON ROR Re eT ie etna cet eh penis Arye neem nren ee Sener ere te rere | 
; .8cs Enc a structure, enumeration, or union definitio 
Spemeeeennenne crue Po ADRESSE ELLA, A nit MRPs ADA OOO REDE BE OETSEE LAMAR EAR VIR SSL UE BESS tod LRSM OE EN Bl ARRACAR AE MANALI USE MRMROETANOLY, AF A AMA WE AN ADE WAN ES TEVA EON AS ee 
4 oh en ong ~ Pen a ns 4 ee 3 
i .e@tra nae, SIZe Regin an enumeration definition i 
forever . Bi MURRAY Cate OLIN eta tace CAREY oe SMEAR SERENA RON ONLI NC LOOT PMR IRENA URL. EOE r {AUSSI TNO OSS A De Ce AALBERS SE LTE, AR EMIS ARTISTE LS I LANES AEST iA ONLINE 
i hr -* : i 
i fille “flaename” ; Detine a orogram identifier i 
Grn ard roaies™ PULTE REY CNR SAD AAAI FE A IEE) YE hg 1 6 a CTE BE CRE ARI EA G3 eT WR LONE LS CM EDC IRB NS ch TG Le SIE Li Ee eG USNS ADLER TPA ML TAIL LTT ALS 2 

H & ee ‘ j 
i ; Begin a function Gefinition 
‘ Oc er" AAS TUM GIDL RENAL LOADS OPN ARES PL AALHD I BSL LIE ERE AL IES BEL ID SARNIA BABA CMI IR EG LES TOON A bere Ne Dd Se LDV > LIRA DOTTY VIR REET RIR ANGOLA FLYNN SLI TEERIRICT, 8 BATE SDS CAIN ITS WU AT SAR ORT 
: i 
$ 7 ¢ “ +i 4 
: r Ladaress i Seec fy the line numbe ar of a C source statement | 
4 OE ATE ASUEEESAANUE EA SOS NE sea scainisean dt iaiad napinsstanambasl fk sak eh sate Aan Atv HE a 62 0 Nak AR LEO SOLARA ALO LEELA LO EE AOR BRST ON oS RATS ARR RL LEAR SALE 
née, valine f, type. storage class. ; Define a 1 member of a structure, enumeration, cr | 
dims j i union 
: pc i ais a ou eta iis a alee Saag ri i lr ir eps bg hh das inne Se nace 


) Sein a structure detinition 


bid 


wa 
si 
cr 

os 


value [,ivpe, s Seec. ify symbolic debug information for a: 


i 
. { 
wlap 2 | } ehigy : 
GdPT§ : ' YENI ICING, iccal variable, or a function f 
j ; i : 


ATALANTA Gn INE RE ABI AAAS TG SM METRE EL BAMA BBS EE AES, ET ORR OOS EAT ATED IG SORIA RAE LET 8 ARS ON 


oc ‘ 
% é, $e, $y { 

IT fo i} aunion cetinition : 

seat Pane sa ta a BA tN RR TITRE REAEALAAE *tte «~ en nc er msimneas AEN ARTE ALO Aaa SIRO SONA at DI A aR RESORT A I REED RAN RnR ta ne NS AER 


ancdix 5 


J ro 4 wl : ye fers 
3 i Ler ee CUSECUYES are SCUSSS ac HE Ag! 


Gj 
re) 
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5.2 Sections Directives 


5-4 


Six directives associate the various portions of an assembly language program 
with the appropriate sections: 


The .bss directive reserves space in the .bss section for variables. 


The .usect directive reserves space in an uninitialized named section. 
The .usect directive is similar to the .bss directive, but it allows you to 
reserve Space separately from the .bss section. 


The .text directive identifies portions of code in the .text section. The 
text section usually contains executable code. 


The .data directive identifies portions of code in the .data section. The 
.data section usually contains initialized data. 


The .sect directive defines initialized named sections, and associates 
subsequent code or data with that section. Named sections are initial- 
ized and contain code or data. 


The .asect directive creates initialized named sections that have abso- 
lute addresses. (Within an absolute section, you can use the .label di- 
rective to define labels with absolute addresses.) 


Section 3 discusses COFF sections in detail. 


Figure 5-1shows how you can use sections directives to associate code and 
data with the proper sections. This is an output listing; column 1 shows line 
numbers, and column 2 shows the section program counter. Each section has 
its Own program counter, or SPC. When code is first placed in a section, its 
SPC equals 0. When you resume assembling into a section, its SPC will re- 


sume 


counting as if there had been no intervening code. 


After the code in Figure 5-1 is assembled, the sections contain the following: 


text 
.data 


Initializes words with the values 1, 2, 3, 4, 5, 6, 7, and 8 
Initializes words with the values 9, 10, 11, 12, 13, 14, 15, 
and 16 


var—defs Initializes words with the values 17 and 18 


.bss 
XY 


Reserves 19 words © 
Reserves 20 words 


Note that the .bss and .usect directives do not end the current section or begin 
new sections; they reserve the specified amount of space, and then the as- 
sembler resumes assembling code or data into the current section. 


000000 
000000 
OO0O0001 
000002 
000003 


000000 
000000 
000001 
000002 
000003 


000000 
000000 
O00001 


000004 
000004 
000005 


000000 


000006 
000007 


000004 
000004 
000005 


000000 


000006 
000007 


00000001 
00000002 
00000003 
00000004 


00000009 
OOQOOO0A 
OOQOO000B 
QOOOQ0000C 


00000011 
00000012 


OOO0000D 
QOQOOQO00E 


OOOOO000F 
00000010 


00000005 
00000006 


00000007 
00000008 
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RREKEKEREKERERKEKERKEKRKEEKEKRRERERERKRREKKEEREREKEKREKKE 


* Start assembling into the .text section * 
KKKEKREKKERKEKKKEKRERKKKRRKEKKEREKEKRKEKRERREKRKEKEKKEKKEKEKEES 


-text 
-word 


.word 


KHEKRKKEKEKEKEKKEKKKEKEKEKEKEREKRREKRKRRERRKKKREKRKKEKEKRKRKKRRKRKEKE 
* Start assembling into the .data section * 
KKRKEKRKERKERKEKKKRERKRKRRKKKEKRKRKEEKREKKRKEKKRRERRKEKKRKRKRKRKEKEK 
-data 
-word 9, 


.-word 2s: (22 


KREKKKKEKKEEREKRKRKEEKRERERKERREKREEKRREREKRRREKRRKEKREKREKEE 


* Start assembling into named section, * 


* var—defs * 
KRRKEKKKKEKRKRRE RRR REE KRRRE RK RKRKRRRKRKRRRERE KER 


"Var—defs" 


ivy. 28 


-Ssect 
.word 


KEREKREKEEKERRKERKREKREKEEKERKEERREREKRRKERERKEREEKREKRE RE 


* Resume assembling into the .data section * 
KRKEKEKKEKERKKRERERRRKERRERKRERREKRRERREREREKREERERKEESR 


-data 


.word 13, 14 


.bss 


Reserve space in 


sym,19 : 


.word 15; 16 ; Still in .data 


KRERKKKKEKKEKKEKEKEKEREREKRREKEKRREREKREKEKKRKEKKKEKEKESE 


* Resume assembling into the .text section * 
KR KR KR KK RK RK IK RK KERR KR RK KEK RK KEE K RRR KEK KEKE 
-text 
.word D4: iO 


-usect 


.word Still in .text 


rigure 5-1. Examples of Sections Directives 


-O0sSs 


Reserve space in xy 
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5.3 Directives that Initialize Memory 


5-6 


Several directives assemble values into the current section: 


& The .set directive equates a value with a symbol. This type of symbol 
is known as an assembly-time constant; it can be used in the same 
manner as a numeric constant (for example, in expressions). 


This example defines a symbol named bval and assigns the value 4 to 
it. The symbol bval can then be used as a constant. 

0001 00000004 _  ~=saibbvail .set 4 

0002 000000 00000004 -byte  bval, bval*2, bval+12 


000001 00000008 
000002 00000010 


Note that the set directive produces no object code. 


e The .byte directive places one or more 8-bit values into consecutive 
words in the current section. This directive is similar to .word, except 
that the width of each value is restricted to 8 bits. 


@ The .hword directive places one or more 16-bit half-word values into 
consecutive words in the current section. This directive is similar to 
.word, except that the width of each value is restricted to 16 bits. 


€ The .word, .int, and .long directives place one or more 32-bit values 
into consecutive locations in the current section. 


® The .string directive places 8-bit characters from one or more character 
strings into the current section. This directive is similar to .byte, except 
that four 8-bit values are packed into each word. The last word in a 
string is padded with null characters (Os) if necessary. 


© The .float directive calculates the single-precision (32-bit) floating- 
point representations of specified floating-point values, and stores them 
in consecutive words in the current section. Here’s an example of a .float 
directive and the object code that it generates: 


0005 000003 O0274ED91 -float 7.654 


Figure 5-2 compares the .byte, .hword, .word, and .string directives; for this 
example, assume the following code was assembled: 


0001 000000 OCOO0000AB . byte OABh 
0002 000001 OOOOCDEF -hword OCDEFh 
0003 000002 89ABCDEF .word O89ABCDEFh 
0004 000003 706C6568 .string "help" 
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SRN OE REE LDR TNT gaa 


Word Contents Code 
31 0 
| 
‘| 0 0 0 3 ae gee © € A B 4 oyte OABh 
Ncecceiens Acerca vested 
1 byte 
| 
2 $word OCDEFh 
3 word O8SABCDEFh 
4A String “help” 


Figure 5-2. Examples of Initialization Directives 


The .field directive places a single value into a specified number of bits 
in the current word. You can pack multiple fields into a single word; the 
assembler will not increment the SPC until a word ts filled. 


Figure 5-3 shows how fields are packed into a word. For this example, 
assume the following code has been assembled; notice that the SPC 
doesn’t change (the fields are packed into the same word): 


C006 000004 00000003 .field 3,4 
0007 000004 00000083 -field 8,5 
0008 000004 00002083 .field £6, 7 


Figure 5-3. An Example of the .field Directive 
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The .space directive reserves a specified number of words in the current 
section. The assembler fills these reserved words with Qs. 


Figure 5-4 shows an example of the .space directive; assume the fol- 
lowing code has been assembled: 


0154 00027A O80F000C LDI AR4,AR7 
0155 00027B 00000000 -space 27 
0156 000296 OQ00000F “word 15 


(a) Current 
SPC = 2/ words 


=F New SPC = 296h 


after assembling a 
space directive to 
. jorrr es is reserve 27 words 


Figure 5-4. An Example of the .space Directive 
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5.4 Directives that Align the Section Program Counter 
@ 


(a) Current 
SPC = OC11th 


The .align directive aligns the SPC on a 32-word boundary. This en- 
sures that the code following the .align directive begins on a cache 
boundary. If the SPC is already aligned at a 32-word boundary, then it 


31 
0 0000000000000 0 0 Bt oS 


is not incremented and .align has no effect. Figure 5-5 shows an ex- 


ample of the .align directive; assume that the following code has been 
assembied: 


0201 000C11 00000000 : 
0202 Q00C20 00000004 -byte 4 


(b) New SPC = 0C200 
after assembling 


32 instruction an .align directive 


words 


OC20h 


32 instruction 
words 


0C40h 


— we ey 
~ew 


oe ee oe oe 


Figure 5-5. An Example of the .align Directive 


The .even directive aligns the SPC so that it points to the next full word. 
You should use .even after using .field directives; if the .field directive 
doesn’t fill a word, the .even directive forces the assembler to write out 
the full word and fill the unused bits with Os. 


Figure 5-3 (page 5-7) illustrates the .field directive; Figure 5-6 shows 


the effect of assembling a .even directive after a .field directive. Assume 
the following code has been assembled: 


0006 000004 00000003 field 


: 3,4 
0007 000004 00000083 -field S45 
0008 000004 00002083 -field 16,7 
0009 000005 


These bits are filled with Os 


These bits were filled by .field directives 
after assembling an .even directive 


Figure 5-6. An Example of the .even Directive 
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“tee 


5.5 Directives that Format the Output Listing 


Seven directives format the listing file: 


@ The .jength directive controls the page length of the listing file. You 
can use this directive to adjust listings for various output devices. 


® The .width directive controls the page width of the listing file. You can 
use this directive to adjust listings for various output devices. 


2 The .list and .nolist directives turn the output listing on and off. You 
can use the .nolist directive to stop the assembler from printing selected 
source statements in the listing file. Use the .list directive to turn the 
listing back on. 


@ The .mlist and .mnotist directives allow and inhibit macro expansion 
listings. 


@ The .option directive controis several features in the listing file. This 
directive has several operands: 


Limits the listing of .bvte directives to 7 line. 

Limits the listing of -hword directives to 7 line. 

Resets the B, H, L, M, and T options. 

Limits the listing of .long, .int, and .word directives to 7 line. 
Limits macro expansions to 7 line. 

Limits the listing of .string directives to 1 line. 

Produces a cross-reference listing of symbols. (You can also ob- 


. 


tain 4 cross-reference listing by invoking the assembier with the -x 
option.) 


2renrw 


My 


corres 


@ 


ae 


eens ie 2 “yyy oy a ; q S yen te 5 Sha é Hl ES etn ome em 
@ The .page directive causes a page eject in the outout isting. 


fcie directive supplies a tite that the assembler prints on the sec- 
nd line of each page. 
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5.6 Conditional Assembly Directives 


Three directives allow you to assemble conditional blocks of code: 


@ The .ff directive marks the beginning of a conditional block. The .if di- 
rective has one parameter, which is an expression. 


= lf this expression evaluates to true (a nonzero value), then the as- 
sembler assembles the code that follows it (up to an .else or .en- 
dif). 


= If this expression evaluates to fa/se (0), then the assembler as- 
sembles code that follows an .else (if present) or an .endif (if no 
else is present). 


o The .eise directive identifies a block of code that the assembler assem- 
bles if the \f-expression is false (0). This directive is optional in the 
conditional btock; if an expression is false and there is no .else statement, 
then the assembler continues with the code that joliows the .endif. 


@ 


The .endit directive terminates a conditional biock. 


The assembier supports several relational operators that are especially useful 
for conditional expressions; see Section 4.8.4 on page 4-13 for more infor- 
mation about relational operators. Figure 5-/ shows an example of conditional 


assembly. 
street a 
| Q001 09000001 syml -set a : 
| 0002 00000002 sym2 set 2 | 
0003 90000003 sym3 .set = 
| 0004 00000004 = sym4 set, 4 
§ 60005 pa ae Oe ae eyml < sym2 
| 9906 o0c000 090900001 -byte syml i 
elise : 
byte sym2 
endif 
Tia2 LE svml + sym2 = sym4 
byte syml + sym2 
else i 
byte sym4 ; 
endif 
cif eee, aya evml <> sym4 - svm2 ‘ 
: “ + ; 
-byte syml ‘ 
elise 
-byte sym4 - symzZ 
enagif 
f 


a SUE AA 10 POEL a aU PG AO SITY AR RI RUT Me OOM DADE I) AARON PET LS ATES “CASON MRED EG NA ERAT CED A SONI ROPE STANCE MORO I SFE UNA CI ARORA EA EAN EROTICA ELIF SO 


Figure 6-7. Am Exemple of Conditional Assembly Directives 
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5.7 Directives that Reference Other Files 


These directives supply information for or about other files. 


The .copy and .include directives tell the assembler to begin reading 
source statements from another file. When the assembler is done reading 
the source statements in the copy/include file, it resumes reading source 
statements from the current file. The statements read from a copied file 
are printed in the listing file; the statements read from an included file 
are not printed in the listing file. 


The .global directive declares a symbol to be external so that it is avail- 
able to other modules at link time. The .global directive does double 
duty, acting as a .def for defined symbols and as a .ref for undefined 
symbols. Note that the linker will resolve an undefined global symbol 
only if it is used in the program. 


The .def directive identifies a symbol that is defined in the current 
moduie and can be used by other modules. The assembler puts the 
symbol in the symbol table. 


The .ref directive identifies a symbol that is used in the current module 
but defined in another module. The assembler marks the symbol as an 
undefined external symbol and puts it in the object symbol table so the 
linker can resolve its definition. 


The .mlib directive supplies the assembler with the name of an archive 
library that contains macro definitions. When the assembler encounters 
a macro that is not defined in the current module, it will then be able to 
search for it in the specified macro library. 
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5.8 Directives Reference 


The remainder of this chapter is a reference. Generally, the directives are or- 
ganized alphabetically, one directive per page; however, related directives 
(such as .if/.else/.endif) are presented together on one page. Here’s an al- 
phabetical table of contents for the directives reference: 


Directive Page 
CUNY GREY, neta celeron eee tact ee caer ieee etanie Sea ema sad aden n ioeta a eeaatnaiats 5-14 
OASCCU. iaiters Gdosee sh Nhat ee ee eee ts a Ol an lee aet chelate eee beteaatelal had dae 5-15 
DGS > ocd ptaneeeuonaadiae poss al oad sateh a UMass ucaan decane setacesana ain manab cea bentiametes maeey 5-17 
214 1c SEES ee ee AC ES en oe ae 5-18 
CY eaten tet cea aac aoc hese te Atalanta emaniean eat 5-19 
(0 [5 | ic eee ROR a PS Ne a a ON aN CTP Re OE OR eee oT 5-20 
3 {= eos Seen eRE RR RET PUR ER REG ROR om Bot CNN PER TOEON CRON Ana Weis OCR ERIE ER SA AT 5 Aes Ton RCN PO RTE 5-26 
Ue ah 2a alate eiaat cena ackc we sath eet oc stieee acta tes caceaa dv ack acetate oune donates eaumnetoains 5-29 
[251 9.18 (eee ee eS RO RIS PR PTE ER YB UU CA SRE OO ROOT ENACT TT A ENE one ery 5-21 
(21 8 6 19 mea Pre ne eo eC oe Bete one sty AE TEA A ee PM MORRO tre PLE RRC SE ROR oe RET IP 5-29 
[SAL 5) | Lae a ans MERE Ieee Rn gE aS CN MAR ASNT RUNEE DE Ree eC Ee Tene e Saaen eee mre 5-22 
TAN css Sasha ce Meek Page oa hele a cetith  rct sat hk cia OA aan ae Rte dana ues 5-23 
TOAD vc siatestle aesthetic a desc ests gsee mane cede nine sae acbictin ach eeteaaobeusacaacae: 5-25 
LOAN ecaecetcoe tah scat aca o sl ateya asad eh ninaacbineMarner en Cueeencenh eter nneemastaaa 5-26 
TUN ON nce cst cath heared ee seeds pan caats bisteesac cesunedapd es cenwer eluate ed daactaewesessaateans des 5-28 
[lee cpictecebetetet teeta scala dates Medes Nts eel neater Sate aot hee Danan ate on ween ia eeeaae tie 5-29 
FEC O can ody 2 ne atac cectee sect gechcce en cen stat etans tet isuuatate ne oo Uamhene aeiet eet iea cue asoreceaeeeeuies 5-18 
1 5 | Rane aE el Oe eR EO Sec re TAT Pee ER Re ee ee ee 5-30 
FAG code ecte ons ec atone te cch teaceiat ernacetaceeet Motes cece tp casceenec sien eutenth teem catahadeee ican. 5-15 
(1a 6 10 a Ramee tty eerie ean Peon as ns BD Sree OR Ree ine nt Nor Line ee net eenren yer rere erate 5-31 
Detect a tasers eres atte cia lous selotes ea anes econ beg maser racine aiteee bh asmeeeenenteneace: 5-32 
NOVA he sicteia teeth bce toeicas ta atop serrataclacmse ane enm tee Gatien batumnausees a vavadsatene la ceacteas eeAatueaimalins 5-30 
LL 2 Ea ee ener tne RRM TLE Set Bnet ETS MOVIE OPTS ONSTAR cP 5-33 
BMS nce ee acca at Reet seeear sone teesmee  e eet etat te Sees Aes a ac ue cathe ace oes ee nance tae 5-34 
EVD GUS Uae sire pasatacs ob cercecituts aa tian atest caltana wi Atraegia cat estemautiana Cindi ohana locale a cnoiedeoneecuneretinnte 5-34 
PEND PS oretersiers teeta eee ano ea estes ewer ate Nas atacand rletei eee eerie es aan ces: 5-32 
SOD WOU ieso eased casua sian Posture aide ease camectel ocak Aachen sinteve ceautebe nasa exe eben been 5-35 
TA Cisse ot a caratteie esi eite sa battensasaee ocala da Suatee decintanipa Staiau te sua Dstaadaneee Ml daawaeneseautensenooteenn ee 5-36 
PO hea trast car aoe nad cuit Pres uS dvanctin depen Meta dada tuasansyacianeeneaasae nates 5-26 
1c | 65 gee PRA Reo RY ST PP Ce en 5-37 
SOE seceesscteetces a as eataet Accs eed ety acs cea eats bed ean aaeiassacteeseaiaanastechadietemnataen dads 5-38 
SSE) ACC sath esse os tte sada ccarcas dana ectine vasudirsaede ceases aise Saatsh aceacu dade tone ownagennes 5-39 
SURG: cesshaca eats os sates ead ase eicauederanedieedacusene eines aes Gout iit 2 5-40 
S24 gene NES POP ERDA SCAU OORT RRNA ATS CRORE TUE AT ATI NORE LIE? LRESE TALES HERTS MAN MOP AE RT TOAD) BEET OT ATES 5-41 
NTU aisaianssiesserecacelacriGiun ee wteachew cee a ndisushaiuladict ale dents dead tuts aeouteeasienccadaeceda aiden ee eens pee 5-42 
RS OB re east a ate eee eet eatse a eee enna amen a aan agian arcs ae 5-43 
TNA, 0 6 9 Ott ne ne eRe eto =f a NESSE eats APSO ee CO ener eR SU ER ON ee rt MC 5-31 
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Syntax 


Description 


Example 


Boundary 


align . 


The .align directive aligns the section program counter on the next 32-word 
boundary. If necessary, the assembler assembles words containing NOPs. 
This directive is useful for aligning code on a cache boundary. 


Using the .align directive has two effects: 


© The assembler aligns the SPC on a 32-word boundary within the 
current section. 


© The assembler, sets a flag that forces the linker to align the entire sec- 
tion on a 32-word boundary. This ensures that individual alignments 
remain intact when a section is loaded into memory. 


This example aligns the SPC on the next 32-word boundary to ensure that 
the code that follows it will start on a cache boundary. Figure 5-8 shows 
how this code aligns the SPC. 


0001 000000 08010000 LDI RO,R1 
0002 

0003 000020 -align 

0004 

0005 000020 08010000 x: LDI RO,R1 
0006 000021 08010000 LDI RO,R1L 
0007 000022 00000000 -space 25 
0008 

COO09 000040 -align 


20h | 


=m ew ow oo 
ee 


(a) LDI RO, R14 (b) .align : a 
SPC = 36h SPC = 40h 
1 
4 ! i 4 
: " ! " 
(c) LDI RO, R1 (d) .align 
LDI RO, R1 
space 25 


Figure 5-8. An Example of the .align Directive 


Define an Absolute Section .asect/.label 


Syntax 


Description 


Example 


sasect “section name” [, address] 


label symbol! 


The .asect directive defines a named section whose addresses are absolute 
with respect to address. 


@ The section name is a required parameter that identifies the name of 
the absolute section. The name must be enclosed in double quotes. 


@ The address required parameter identifies the section’s absolute start- 
ing address in target memory. This address is required the first time 
that you assemble into a specific absolute section. {f you use .asect 
to continue assembling into an absolute section that already contains 
code, you cannot use the address parameter. 


Absolute sections are useful for loading sections of code from off-chip 
memory into faster on-chip memory. In order to use an absolute section, 
you must know which location you want the section to execute from, and 
specify it as the address parameter. 


Most sections directives create sections with relocatable addresses. The 
starting SPC value for these sections is always zero; the linker then relocates 
them where appropriate. The starting SPC value for an absolute section, 
however, is the specified address. The addresses of all code assembled into 
an absolute section are offsets from the specified address. The linker does 
relocate sections defined with .asect; however, any labels defined within 
an absolute section retain their absolute (runtime) addresses. Thus, refer- 
ences to these labels refer to their runtime addresses, even though the sec- 
tion is not initially loaded at its runtime address. 


All labels in an absolute section have absolute addresses. The .Jabel direc- 
tive creates “labels” with relocatable addresses; this allows you to define a 
symbol that points to the section’s loadtime location in off-chip memory. 
The .label directive can only be used within an absolute section. 


Note that after you define a section with .asect, you can use the .sect di- 
rective later in the program to continue assembling code into the absolute 
section. 


This example defines an absolute section called abs. At run time, this sec- 
tion will start at address 100h in on-chip RAM. copy—start is a relo- 
catable symbol that points to the section’s loadtime address in off-chip 
ROM. The symbols abs—code and abs—end are absolute addresses; 
abs—_code - abs—end yields the number of lines of code to move. The 
function copy copies the section from ROM into RAM. 


Figure 5-9 shows how the code is copied from one part of memory to an- 
other. 


.asect/.label 
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O00010U 
000100 
000100 
000101 
000102 
000103 


000000 
000000 
OO00001 


000000 
000000 
OO0001 
000002 
000003 
000004 


000005 


000006 
000007 
000008 


copy.start —-—> 


Define an Absolute Section 


KRHRKEKKEKEKERKRKRERRKRKREKRRREKRRRRKERKRKRRERERREKRERKRRRRRERERE 


* Define an absolute section. 


This section can * 


* be linked and loaded into external ROM, then * 


* copied into internal RAM and run. 
KERR KEKKREKEKE KEKE KR KER KR REE KERR EERE KKRKEKRAKRKRKAKEE 


"abs" 7 


copy—start 
0,RO 


100 


*ARO++,RO 


100h 


« 
a 


° 
f 


* 


dest addr in RAM 
src addr in ROM 


RRERKKRKEREEKRERERREREERRREKRRKEKRRERKRREKEKRKEKRRKERRREKKREE 
* This function copies the absolute section * 


* 


KEKE KKEEKREKRREREKEREKREKRKEKREREEKKREREKEREKKEEREKEKRKEEKEKEE 


copy—start 


ptr to code in ROM 


abs—code ; Gest addr in RAM 
@L1,ARO s 1080 Sre prey 
@L2,AR1 ; load dest ptr 
*ARO+4+,RO ; load first word 
abs—end - abs—code 

*ARO++,RO ; copy all bytes 
RO, *AR1++ 


e 
, 


end copy 


BREE KEKEREKREREKEKRKEEKREREREERKREEREEERERKEERREREREREKEEKRE 


* Main program -- copy the routine into RAM, as 


* 


KRRERREKRRRREKRERRRRRRREEEREKRRERERRERERRERRERRRRERREREREER 


copy 
abs—code 


-asect 
-label 
08600000 abs—code: LDI 
13FB0064 RPTS 
02402001 ADDI 
78800000 abs—end: RETS 
* from ROM to RAM. 
-data 
00000100+ Lil -word 
OO0000100+ L2 .word 
-text 
08280000+ copy: LDI 
08290001+ LDI 
08402001 LDI 
13FB0003 RPTS 
DA002120 LDI 
2 STI 
78800000 RETS 
* then run. 
62000000+ run: CALL 
62000100 CALL 
78800000 RETS 


External ROM 


08600000 | 
13FB0064 | 
02402001 
78800000 | 


Figure 5-9. An Example of the 


Internal RAM 


08600000 


13FB0064 


02402001 
78800000 \}«———— abs_end 


abs_code = 100h 


.asect Directive 


Assemble into .bss Section .bss 


Syntax 


Description 


Example 


-bss symbol, size in words 


The .bss directive reserves space in the .bss section for variables. This di- 
rective is usually used to allocate variables into RAM. 


® The symbo/ is a required parameter. It defines a symbol that points 
to the first location reserved by the directive. The symbol name 
should correspond to the variable that you’re reserving space for. 


® The size is a required parameter; it must be an absolute expression. 
The assembler allocates size words in the .bss section. There is no 
default size. 


Note that the .usect directive is similar to the .bss directive; it also reserves 
space in memory. However, .usect creates named uninitialized sections that 
can be allocated separately from the .bss section. 


Other section directives (.text, .data, .sect, and .asect) end the current sec- 
tion and begin assembling into another section. The .bss directive, how- 
ever, does not affect the current section. The assembler assembles the .bss 
directive and then resumes assembling code into the current section. For 
more information about COFF sections, see Section 3. 


This example uses the .bss directive to allocate space for two variables, 
array and dflag. The symbol array points to 100 words of uninitialized 
space (the .bss SPC = 0). The symbol dflag points to 1 word of unini- 
tialized space (the .bss SPC = 100). This example reserves a total of 101 
words in the .bss section. Note that symbols declared with the .bss direc- 
tive can be referenced in the same manner as other symbols and can also 
be declared external. 


oss Assemble into .boss Section 


COOL KERR KEKRERKRERERKRERERKRREKKRRRKRRE KR 
0002 * Begin assembling into .text * 
0003 KREKKKAEKERKRKEKEEKKERKEKEKKKREEREKREEEESE 
0004 Q00000 -text 

0005 000000 08010000 LDI RO,R1 

0006 

COCT KRKEKEEKREREKEKEREKRRKEKRKREKRKKEKRRKRKARREK 
0008 * Allocate 100 words in .bss * 
Occs KKEKREKEKREKRREKRKEKREKERKEKEKREKRREERKREE 
0010 Q00000 -bss array,100 

OO1l 

OO 12 KRHKEKEKREKRKEE KER KKREKRKEKKEREKREKRKREKAEEKE 
0013 Cai). am text x 
0014 RREREKREKEKEKEKRKEKERERKEKREKREKERRERKEEE 
O0C15 O00CCO1 08020001 LDI Ri R2 

0016 

OOL7 KHKEKEAEKEKRKEKKEKREKEKRKREKKKRKRKRRKKEKRKKKEaEKE 
0018 - Allocate 1 word in .bss * 
OOL9S REREKEKEKEKKEREKREKKEKKEKEEKEKRKKEREKRKKEEEK 
0020 000064 .bss adflag,1 

0021 

002? KRREREREKEKKRKRKRKEKKRKEEKEKREKEKRKEEKERKEEKRSE 
0023 a Sti: 2m: .cext * 
0024 KREKKERKEKKREEKREREKKRREKRKEEEERKEKKEKKKE EK 
0025 OC00002 O08020064+ LDI @dflag,RO 

C026 

C0027 KEERKKEKERRKKRERRKEKEKREEREKEREREERE 
0028 * Declare external .bss symbol * 
0023 KRERKKEEKRKEKREKAERKKEKRKKKREKRKEKEAEKKEKAEESEK 
C036 -global array 


avi 
i 
OG 


Initialize Byte .byte 


Syntax 


Description 


Example 


«byte va/ue; [,..., value,/] 


The .byte directive places one or more 8-bit values into consecutive words 
in the current section. Each va/ue can be either: 


@ An expression which the assembler evaluates and treats as an 8-bit 
signed number. 


@ A character string enclosed in double quotes. Each character repres- 
ents a separate value. 


Values are not packed or sign extended; each byte value occupies the least 
significant 8 bits of a full 32-bit word. The assembler truncates values that 
are greater than 8 bits. You can use up to 100 values, but the total line 
length cannot exceed 200 characters. Each character in a string is counted 
as a separate operand. 


If you use a label, it points to the location at which the assembler places the 
first byte. 


This example places the 8-bit values 10, -1, 97, 98, 99, and 97 into six 
consecutive words in memory. The label strx has the value 64h, which is 
the location of the first initialized word. 


0002 000064 OOOO000A) strx: . byte 10,-1,"abe",'a' 
000065 OOOOOOFF 
000066 OOOOO0NSG1L 
000067 O0000062 
000068 00000063 
000069 OOOCOO00S61 


.copy/.include Read Statements from Another Source File 


Syntax 


Description 
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copy /" /filename[” ] 


.include ["Jfilename["] 


(The quote marks surrounding the filename are optional.) 


The .copy and .include directives tell the assembler to read source siate- 
ments from a different file. The assembler: 


1) Stops assembling statements in the current source file. 
2) Assembles the statements in the copied/included file, and 


3) | Resumes assembling statements in the main source file, starting with 
the statement that follows the .copy or .include directive. 


The filename is a required parameter that names a source file; the filename 
may be enclosed in double quotes. The fi/ename must follow operating 
system conventions. You can specify a full pathname (for example, . copy 
c:\dsp\filel.asm). If you do not specify a full pathname, the assembler 
searches for the file in: 


1) | The directory that contains the current source file. 
2) Any directories named with the -i assembler option. 
3) Any directories specified by the environment variable A—DIR. 


For more information about the -i option and the environment variable, see 
Section 4.3, Specifying Alternate Directories for Assembler Input, on page 
4-4, 


The statements that are assembled from a copy file are printed in the as- 
sembly listing. The statements that are assembled from an included file are 
not printed in the assembly listing, regardless of the number of .list/.nolist 
directives that are assembled. 


The .copy and .include directives may be nested within a file being copied 
or included. The assembler limits this type of nesting to eight levels; the 
host operating system may set additional restrictions. The assembler pre- 
cedes the line numbers of copied files with a letter code to identify the level 
of copying. An A indicates the first copied file, B indicates a second copied 
file, etc. 


Read Statements from Another Source File .copy/.include 


Example 1 This example uses the .copy directive to read and assemble source state- 
ments from other files and then resumes assembling into the current file. 


Listing file: 


0001 000000 00000000 .space 20 
0002 . cCOpy "byte.asm" 
AOOO1 ** In byte.asm 
A0002 000014 00000020 -byte 32, 1+'A' 
000015 00000042 
A0003 .copy "word.asm" 
BOOO1 ** In word.asm 
BOOO2 000016 OOOOAABB -word QAABBh, 56q 
000017 0000002E | 
A0004 ** Back in byte.asm 
A0005 000018 O000006A byte 67h+3 
0003 
0004 ** Back in original file 
0005 000019 656E6F44 .string "Done" 
Example 2 This example uses the .include directive to read and assemble source 
statements from other files and then resumes assembling into the current 
file. 


word2.asm 
(second include file) 


include.asm 
(source file) 


byte2.asm 
(first include file) 


** In word2.asm 
-word OABCDh, 56g 


-Sspace VAS) 
-include "byte2.asm" 


** In byte2.asm 
-byte 325 bo TA! 
-include "word2.asm" 


**Back in original file ** Back in byte2.asm 


-string "Done" -byte 67h+3 
Listing file 
0001 0000 .space 29 
0002 -include "byte2.asm" 


5-21 


.data 


Syntax 


Description 


Example 
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0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
0010 
OO 11 
0012 
0013 
0014 
QOO015 
0016 
0017 
0018 
0019 
0020 
0021 
0022 
0023 
0024 
0025 
0026 
0027 
0028 
0029 
0030 
0031 
0032 
0033 
0034 


.data 


The .data directive tells the assembler to begin assembling source code into 
the .data section; .data becomes the current section. The .data section is 


Assemble into .data Section 


normally used to contain tables of data or preinitialized variables. 


Section 3 provides a detailed explanation about COFF sections. 


Note that the assembler assumes that .text is the default section. Therefore, 
at the beginning of an assembly, the assembler assembles code into the 


.text section unless you specify an explicit section control directive. 


This example assembles code into the .data and .text sections. 


000000 
000000 


000000 
000000 


QOo000CC 
OOO0O0CC 


QOOO0O0CD 


OOOOCE 


QO00001 
Oo00001 


OOOOCF 


00000000 


00800000 


EPPREEEE 
QOQOQOOOFF 


08010000 


08010000 


RKKEKRKKEKREKEKKREKRKEERKRKRREEKREKEKRREKRERERKEKKEKEEEEEE 


ade Reserve space in .data =* 
KRREEKRKEKEKEKREKEREKREREKRKEREKREKREREREKKEREEKRKEKKRKEEKSE 
.data 


-space OCCh 


RERKEEKEKEKERKKEKERKEKREREKREREKERRERERKRKEKEEKRKERERER 


** Assemble into .text *x* 
KEE KRKRKRKRKRR RRA RRR: 
-text 


ABSI RO 


BRERKEKEKREKREKRKEEREKREREKRRRRKERRRREREKEKEKRERERRREEE 


* Assemble into .data *x* 
KKK KKKKRKKKR KKK KKK 


table: -data 
.word =1 ; Assemble 32-bit 
; constant into .data 
-byte OFFh ; Assemble 8-bit 
; constant into .data 
LDI RO,R1 ; Assemble code into 
; .data 


RKRKEREKRKERERERKERKEREREREKRRERREKRKRREKRERKEEKERKREEE 


** Assemble into .text ** 
KEE RK KRREKRRIEIEK 
text 


LDI RO,R1 


RREKRKEKEKRKKKEKRREKEKREKERKEREREREKRERRERKEKEREEE 


wn Resume assembling into .data ae 
ee at address OCFh Ne 
KRKEKEKEKEKRKRKEKEKRKEKEKERKEKEKEKEKEREKREKKRKEKEKRKEKRKEEKREEESE 


-data 


End Assembly .end 


Syntax 


Description 


Example 


.end 


The .end directive is an optional directive that terminates assembly. It 
should be the last source statement of a program. The assembler will ignore 
any source statements that follow an .end directive. 


Note that this directive has the same effect as an end-of-file. 


Caution: 


Do not use the .end directive to terminate a macro: use the 
SENDM macro directive instead. 


This example shows how the .end directive terminates assembly. If any 
source statements followed the .end directive, the assembler would ignore 
them. 


0001 000000 Text—Start: text 

0002 O0O0000 OOCOOCOOA .byte OAh 

0003 000001 OOOOCAAAA .word OAAAAh 

0004 000002 41414141 .string "AAAAAAAA" 
000003 41414141 

0005 -end 
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even Align SPC at Next Word Boundary 


Syntax even 


Description — The .even directive aligns the section program counter on the next full 
| word. When you use the .field directive, you can follow it with the .even 
directive. This forces the assembler to write out a partially filled word before 
initializing fields in the next word. The assembler will fill the unused bits 
with Os. If the SPC is already on a word boundary (no word is partially 
filled), then .even has no effect. 


Example Here’s an example of the .even directive. Word 0 is initialized with several 
fields; the .even directive causes the next field to be placed in word 1. 


OoOool1 KHKKKKKEKKEKEKKEKKEKKKEKKKEKEKEKKEKEKE KEKE 
0002 - Initialize .a 2=bit f1eld = 
0003 KEKE KEKKEKKEKRKEKEKKEREKKREKEKE KKK EK 
0004 000000 00000003 -£iLeld O3h,2 

0005 

0006 KHKKKKEKKKKEKEKKEKREREKKEKEKRKKKKR KKK KKK 
0007 ~ Initialize a 5-bit field ie 
0008 RRKKKEKKKKEKKKEKKKEKEKEKEKRKEKREKREKKREEEE 
0009 000000 0000002F -field OBh,5 

0010 

OOL1 KRKEKKKEKEKKEKKEKREKEKKKKEKKKEKKKAKK KEK 
0012 = Write out the word 3 
0013 KKKEKKEKEKKKEKKKKKKEKKEKKEKERKEKRKEEEKEKKEK 
0014 000001 -even 

OOQ15 

0016 KRKKKKREKKKEKKRKEKKKKKKKEKKKEKKEKEEERKEKE 
0017 * This field 1s: -1n. fhe * 
0018 sg next word . 
0019 KKK KK KKK KK ERK KK KK KR KKK KK RR EK 
0020 000001 00000007 -field O7h,3 


Figure 5-10 shows how this example initializes word 0. The first 7 bits are 
initialized by .field directives; the remaining bits are set to O by the .even 
directive. 


31 
0000000000000 000000000 0 O ODEO SE EEE 
ee a, pea 


This part of the word is filled by the .even directive. This part is filled 
by .field directives. 


Figure 5-10. An Example of the .even Directive 
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Initialize Field field 


Syntax field va/ue [,size in bits] 


Description — The .field directive initializes multiple-bit fields within a single word of 
memory. This directive has two operands: 


e The va/ue is a required parameter; it is an expression that is evaluated 
and placed in the field. If the value is relocatable, size must be 32. 


@ The s/ze is an optional parameter; it specifies a number from 1-32, 
which is the number of bits the field consists of. If you do not specify 
a size, the assembler uses a default size of 32 bits. Note that the as- 
sembler will truncate the value if you specify a field that is not wide 
enough to contain the value. For example, .field 3,1 will cause the 
assembler to truncate the value 3 to 1; the assembler will also print 
an error message. 


Successive field directives pack values into the specified number of bits tn 
the current word. Fields are packed starting at the least significant part of 
the word, moving towards the most significant part as more fields are ad- 
ded. If the assembler encounters a field size that will not fit in the current 
word, it writes out the word, increments the SPC, and begins packing fields 
into the next word. 


You can use the .even directive to force the next -field directive to begin 
packing into a new word. 


If you use a label, it points to the word that contains the field. 
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.field Initialize Field 


Example This example shows how fields are packed into a word. Notice that the 
SPC does not change until a word is filled and the next word is begun. 


O001 KKKKKK KEKE KKK KEKE KKEKRKEEKRKKRRK RRR 
0002 * Initialize a 24-bit field * 
0003 KKK KKK KEKE KR RK KER KKK KEKKREKKEKRKE 
0004 000000 OOBBCCDD .field OBBCCDDh, 24 

0005 

0006 KKK KEKE KERR RRR ERK KKK KR RK KK RIE K 
0007 * Initialize a 5-bit field * 
0008 ee ee ee eee ee ee ee 
0009 000000 OABBCCDD .field QAh,5 

0010 

OO11 KK KK KEKE KKK EKER KR KEK KRERKEKRARK KKK KKK 
0012 * Initialize a 4-bit field * 
0013 * (new word) * 
0014 KKK KKK KK KKK RK KK KEK REE KKK 
0015 OO0000L OOOQODCONC .field Och, 4 

0016 

OO17 KKK KKK KERR EKER RRR EKREKRKREKRREKKRKK 
0018 * Initialize a 3-bit field * 
0019 KA KKK KERR KEK RRR KR EKER ERK KR RKEKRA KEKE 
0020 000001 O000001C x: . field 01h, 3 

0021 

0022 HR RRR RI RRR RR RK KR RRR RRR RRR RK KK 
0023 * Initialize a 32-bit relo- * 
0024 * catable field in the next * 
0025 * word * 
0026 KKK KKK RK KEK KKERKRKRKEKEKKKKKRKKRAEK 
0027 000002 OO0OO00001' .field x 


Figure 5-11 (page 5-27) shows how the directives in this example affect 
memory. 
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initialize Field field 


Word 34 Qo Cod 


@® 


(a) O 00111011110011001101 110 14 field OBBCCDDh, 24 
\ eee tee, perenne, 
24-bit field 


SSE field OAh, 5 


Oeot field OCh, 4 


1 1100 
ny a 


3—bit field 


OC}O0000000000000000000 O O O}G:O::43424 0:0) field x 


{e) 1 


2j;j0000000000000000000000000000000 1 


Figure 5-11. An Example of the .fieid Directive 
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float 


Syntax float value; [,..., value,] 


Description _ The .float directive places the floating-point representation of one or more 
floating-point constants into successive words in the current section. Each 
va/ue must be a floating-point constant, or a symbol that has been equated 
to a floating-point constant. Each constant is converted to a floating-point 
value in TMS320C30 single-precision (32-bit) format. 


Example 


0001 
0002 
0003 


0004 


0005 
0006 
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000000 
ooo0o01 
000002 
000003 


000004 


5 3FBACAF 
01400000 
06760000 
FFOQOOQOO0O0 
O1490FCF 
O12aF94C 
O1490FCF 
O12dF94C 


PI: 


E: 


-float 
-float 
-£loat 


-set 
set 
-float 


Here are some examples of the -float directive. 


-1.0e25 
3 
123, 0O. 


3.14159 
2.71828 
PI,E 


Initialize Floating-Point Value 


5 


Global Symbol Definitions .global/.ref/.def 


Syntax 


Description 


Example 


.global symbo/, [...., symbol,] 


def symbol; [,..., symbol,] 


ref symbo/, [,..., symbol,] 


The .global, .def, and .ref directives identify symbols that can be referenced 
externally. 


The .def directive identifies a symbol that is defined in the current 
module and can be accessed by other files. The assembler will place 
this symbol in the symbol table. 


The .ref directive identifies a symbol that is used in the current mod- 
ule but defined in another module. The linker resolves the symbol’s 
definition. 


The .global directive acts as a .ref or a .def, as needed. 


A global symbol is defined in the same manner as any other symbol; that is, 
it appears as a label or is defined by the .set, .usect, or .bss directive. As 
with all symbols, if a global symbol is defined more than once, the linker 
issues a multiple-definition error. Note that .ref always creates an entry for 
a symbol, whether the module uses the symbol or not; .global however, 
only creates a symbol table entry if the module actually uses the symbol. 


A symbol may be declared global for two reasons: 


1) 


2) 


If the symbol is not defined in the current source module (this in- 
cludes macro, .copy, and include files), then the .global or .ref direc- 
tive tells the assembler that the symbol is defined in an external 
module. This prevents the assembler from issuing an unresolved ref- 
erence error. At link time, the linker looks for the symbol’s definition 
in other modules. 


If the symbol is defined in the current module, then the .global or .def 
directive declares that the symbol and its definition can be used ex- 
ternally in other modules. These types of references are resolved at 
link time. 


This exanaple uses four files: 


filel.lst and file3.1st are equivalent. Both files define the 
symbol Init and make it available to other modules; both files use the 
external symbols x, y,and z. filel.1ist uses the .global directive 
to identify these global symbols; file3.1st uses .ref and .def to 
identify the symbols. 


file2.ist and file4.1st are equivalent. Both files define the 
symbols x, y, and z and make them available to other modules; both 
files use the external symbol Init. file2.1st uses the .global di- 
rective to identify these global symbols; file4.1st uses .ref and .def 
to identify the symbols. | 
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global/.ref/.def Global Symbol Definitions 


file1 .Ist: 

OOoO01 ; Global symbol defined in this file 
0002 -global Init 

0003 ; Global symbols defined in file2.l1st 
0004. -global xj; Viz 

0005 000000 Init: ; Symbol definition 
0006 000000 08010000 LDI RO,R1L : 

0007 000001 00000000! .word x 

0008 : : 

0009 ; 

0010 : : 

0011 .end 

file2.ist: 

O000O1 ; Global symbols defined in this file 
0002 -global X,Y,Z 

0003 ; Global symbol defined in filel.lst 
0004 -global Init 

0005 ; Symbol definitions 

0006 00000001 xs .set 1 

0007 00000002 y: .set 2 

0008 00000003 rae -set x + y 

0009 000000 00000000! .word Ent 

0010 ; : 

OO11 : : 

0012 : é 

0013 .end 

file3.Ist: 

0001 ; Global symbol defined in this file 
0002 .def Init 

0003 ; Giobal symbols defined in file4.lst 
0004 .ref X,YV,z2 

0005 000000 Pare: ; Symbol definition 
0006 000000 08010000 LDI RO,R1L 

0007 000001 00000000! .word x 

0008 ; : 

0009 : 

0010 : . 

0011 -end 

file4.Ist: 

ooo1 ; Global symbols defined in this file 
0002 .def X,YV,Z 

0003 ; Global symbol defined in file3.lst 
0004 .ref Init 

0005 ; Symbol definitions 

0006 00000001 Xt .set 

0007 00000002 y: -set 2 

0008 00000003 Z% .set x + y 

0009 000000 00000000! .word Init 

0010 ; ‘ 

OO11 : 

0012 ; , 

0013 .end 
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Initialize Half Word 


Syntax 


Description 


Example 


-hword = va/ue; [...., 


.<hword 


va/ue,] 


The .hword directive places one or more 16-bit values into consecutive 
words in the current section. Each va/ue may be either: 


®@ An expression which the assembler evaluates and treats as a 16-bit 
signed number. 


@ A character string enclosed in double quotes. Each character repres- 


ents a separate value. 


Values are not packed or sign extended; each value occupies the least sig- 
nificant 16 bits of a full 32-bit word. 


The assembler truncates any value that Is greater than 16 bits. The .hword 
directive can have up to 100 operands, but they must fit on a single line. 


If you use a label, it points to the location of the first word that is initialized. 


This example assembles several 16-bit values into words in the current 
section. The label vlist has the value 6Ah, which is the location of the 
first initialized word. 


0003 OOOO6A 
OOO06B 
O00006C 
OO0006D 
OOOO6E 
OOOO06F 


OOOOOO0O0A 
OOOOFFFF 
00000061 
00000062 
00000063 
00006261 


vlist: -hword 10,-1,"abc",'ab' 
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Conditional Assembly 


.f/.else/.endif 
Syntax 
else 
endif 
Description 
the .endif. 

Example 

0001 00000001 

0002 00000002 

0003 00000003 

0004 00000004 

0005 

0006 000003 00000004 

0007 

0008 

0009 

0010 

0011 000004 O0000000A 

0012 

0013 

0014 

0015 

0016 

0017 

0018 000005 00000006 
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0019 


.if well-defined expression 
code to assemble if expression is true 


code to assemble if expression is false 


Three directives provide conditional a 


@ The .if directive marks the eamning ofa conditional block. The ex- 
pression ts a required parameter. 


~ If this expression evaluates to true (a nonzero value), then the 
assembler assembles the code that follows it (up to an .else or 
endif). 


= If this expression evaluates to fa/se (0), then the assembler as- 
sembles code that follows an .else (if present) or an .endif (if 
no .else is present). 


@ The .else dir&ctive identifies a block of code that is assembled when 
the if-expression evaluates to false (0). This directive is optional in 
the conditional block; if an expression is false and there is no .else 
statement, then the assembler continues with the code that follows 


e The .endif directive terminates a conditional block. 


Here are some examples of conditional assembly: 


syml 
sym2 
sym3 
sym4 


If_4: 


Tf_5: 


If_6: 


mWDN-E 


sym4 
sym4 


sym2 


syml 
10 


syml 


sym3 
sym3 


sym4 - 


* sym2 
; Equal values 


; Unequal values 


; Less than/equal 
; Greater than 


{= sym4 + sym2 
; Unequal values 


; Equal values 


Initialize 32-Bit Integer | .int/.long/.word 


Syntax 


Description 


Example 7 


Example 2 


Example 3 


Ant value, [,..., value,] 
jong vafue; /,..., value,] 


word value, [,..., value,] 


The .int, .long, and .word directives are equivalent. These directives place 
one or more values into consecutive 32-bit fields in the current section. 
Each va/ue is either: 


@ An expression which the assembler evaluates and treats as a 32-bit 
signed number. 


@ A character string enclosed in double quotes. Each character repres- 
ents a separate value. 


The va/ues can be either absolute or relocatable expressions. If an ex- 
pression is relocatable, the assembler generates a relocation entry that refers 
to the appropriate symbol; the linker can then correctly patch (relocate) the 
reference. This allows you to initialize memory with pointers to variables 
or labels. 


You can use as many va/ues as fit on a single line. If you use a label, it 
points to the first word that is initialized. 


This example uses the .int directive to initialize words. Notice that the 
symbol symptr puts the symbol’s address in the object code and generates 
a relocatable reference (indicated by the ’ character appended to the object 
word). 


0005 000070 08010000 symptr LDI RO,R1 
0006 000071 OOOQ000A -int 10,symptr,-1,"abe",'abc' 
000072 00000070' 
000073 FFFFFFFF 
000074 OQ0000061 
000075 00000062 
000076 00000063 
000077 00636261 


This example initializes two 32-bit fields and defines DAT1 to point to the 
first location. The contents of the resulting 32-bit fields are OFFFFABCDh 
and 141h. 


0001 000000 FFFFABCD DAT1: .long OFFFFABCDH, 'A'+100h 
000001 00000141 


This example initializes five words. The symbol Wordx points to the first 
word. 


0001 000000 O0O000C80 WordxX: .word 3200,1+'AB',-'AF',OF410h, 'A' 
000001 00004242 
000002 FFFFBOBF 
000003 OQOOOF410 
000004 00000041 
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length/.width Set Listing Page Size 


Syntax length page length 
width page width 
Description The .length directive sets the page length of the output listing file. It af- 
fects the current page and following pages; you can reset the page length 
with another .length directive. 
& Default length: 60 lines 
@ Minimum length: 20 lines 
® Maximum length: 32,767 lines 
The .width directive sets the page width of the output listing file. It affects 
the next line assembled and following unes, you can reset the page width 
with another -width directive. 
e Default width: 80 characters 
@ Minimum width: 80 characters 
8 Maximum width: 200 characters 
Note that the width refers to a full line in a listing file; the line counter value, 
SPC value, and object code are counted as part of the width of a line. 
Comments and other portions of a source statement that extend beyond the 
page width are truncated in the listing. 
The assembler does not list the .width and .length directives. 
Example This example sets the page length and the page width to various values. 
TMS320C30 Assembler Version 1.0, 87.089 Thu May 28 14:44:06 1987 
(c) Copyright 1987, Texas Instruments Inc. 
ReEKX Length and Width ***** PAGE a 
0002 
0003 BRREKKEKEKEKEKEEKKEKKKREKKEREKEKKKREREEKKEREEKKREKREKRKKKRKRKEKKRAKE 
0004 KRRAEKEKEKRKREKEKEKKEKKREKEKREKEKERKRKEKEKRREKRKEKRKRKRKRKKKRKRKRKRKEKESE 
0005 aged The page length is limited to 60 ais 
0006 as lines per page. The page width is el 
0007 *% limited to 80 characters per line. liad 
0008 KREKRKKKREKKRRKERRERRERREKRKEKRKEEKRKRRKERERKRREKRKRKRKKRKKKRR KEK 
0009 KRKEKKKKEEKKEKEKRERRREKRREEKKREREEREKREKRKEKRERERRKKEKRERKREKKEREKE 
0010 
0011 000000 -length 60 
0012 000000 .width 80 
eee KRKKREEKKEKERKEKKRKEEKRKEEREKRKREKEREREKEKRKEREKRKREKEKRERREKEREKREEE 
0015 ee ee ee ee ee ee ee ee ee ee ee ee 
0016 =* The page length is limited to 50 ita 
OO17 kes lines per page. The page width os aad 
0018 we limited to 250 characters per li ** 
0019 ena OE AEA A EK 
0020 KRKEEKKERREKRKEKKRERKRKEKKEKEKKKRREKEEKRRKEREKKRKEKEKRKKRKAEE 
0021 
0022 000000 .length 50 
0023 000000 .width 250 
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Start/Stop Source Listing list/.nolist 


Syntax 


Description 


Example 


list 


nolist 


The .nolist directive suppresses the source listing output until a .list direc- 
tive is encountered. The .list directive tells the assembler to resume printing 
the source listing after it has been stopped by a .nolist directive. By default, 
the assembler behaves as if a .list directive has been specified. The .nolist 
directive can be used to reduce assembly time and the size of the source 
listing; it is frequently used in macro definitions to inhibit the listing of the 
macro expansion. 


The assembler does not print the .list or .nolist directives, or the source 
statements that appear after a .nolist directive; however, it continues to in- 
crement the line counter. You can nest the .list/.nolist directives; each 
-nolist needs a matching .list to restore the listing. At the beginning of an 
assembly, the assembler acts as if it has assembled a .list directive. 


Note: 


If you don’t request a listing file when you invoke the assembler, the 
assembler ignores the .list directive. 


This example uses the .copy directive to insert source statements from an- 
other file. The first time the .copy directive is encountered, the assembler 
lists the copied source lines in the listing file. The second time .copy is 
encountered, the assembler does not list the copied source lines because a 
.nolist directive was assembled. Note that the .nolist, the second .copy, and 
list directives do not appear in the listing file; note also that the line counter 
is incremented even when source statements are not listed. 


Source file: 


-copy byte.asm 
-nolist 
.copy byte.asm 
.list 

* Back in original file 
.string "Done" 


Listing file: 

0001 -COpy byte.asm 
AOOO1 * In byte.asm (copy file) 
AQ002 000000 00000020 .byte 325- be AS 

000001 00000042 
0006 * Back in original file 
0007 000004 656E6F44 .-string "Done" 
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mlib 


Define Macro Library 


Syntax 


Description 


Example 
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.mlib  /" /filename[" ] 


The .mlib directive provides the assembler with the name of a macro library. 
A macro library is a collection of files that contain macro definitions. These 
files are bound into a single file (called an archive or library) by the ar- 
chiver. Each file in a macro library may contain one macro definition that 
corresponds to the name of the file. 


Note that: 
@ Macro library members must be source files (not object files). 


@ The filename of a macro library member must be the same as the 
macro name and its extension must be .asm. 


The filename must follow host operating system conventions; it may be 
enclosed in double quotes. You can specify a full pathname (for example, 
-mlib C:\dsp\macs.1lib). If you do not specify a full pathname, the 
assembler searches for the file in: 


1) The directory that contains the current source file. 
2) Any directories named with the -i assembler option. 
3) Any directories specified by the environment variable A—DIR. 


For more information about the -i option and the environment variable, see 
Section 4.3, Specifying Alternate Directories for Assembler Input, on page 
4-4. 


When the assembler encounters an .mlib directive, it opens the library and 
creates a table of its contents. The assembler enters the names of the indi- 
vidual library members into the opcode table as library entries; this redefines 
any existing opcodes or macros that have the same name. If one of these 
macros is called, the assembler extracts the entry from the library and loads 
it into the macro table. The assembler expands the library entry in the same 
manner as other macros, but it does not place the source code into the 
listing. Only macros that are actually called from the library are extracted. 


This example creates a macro library that defines two macros, inci and 
deci. The file incl.asm contains the definition of incl, and decl.asm 
contains the definition of dec1. 


incl.asm 


* Macro for incrementing 

Inc. SMACRO REG 
ADDI 1,:REG: / 
SENDM 


decl.asm 


* Macro for decrementing 

decl SMACRO REG a 
SUBI 1,:REG: 

SENDM : 


Define Macro Library -.mlib 


Use the archiver to create a macro library: 
ar30 -a mac incl.asm decl.asm 


Now you can use the .mlib directive to reference the macro library and call 
the incl and decl macros: 


-mlib "mac.1lib" 
incl RO ; Macro call 
decl Rl ; Macro call 
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.mlist/.mnolist 


Start/Stop Macro Expansion 


Syntax 


Example 


OOO1 
0002 
0003 
0004 
0005 
{0001 


0006 
0007 
0008 
0009 
1O001 
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000000 
000001 
000002 


000009 
OOOO0O0A 
OOOO0Q0OB 
00000C 
OO000D 
OOOO0OE 


-.mlist 
-mnolist 


Two directives provide you with the ability to control the listing of macro 
expansions in the listing file: 


c The .mlist directive allows macro expansions in the listing file. 


® The .mnolist directive inhibits macro expansions in the listing file. 


By default, all macro expansions are listed. As the example below shows, 
the line counters for macro expansion lines are preceded with an exclama- 
tion mark (!). The line counter restarts counting at 1 during a macro ex- 
pansion; it resumes counting from its previous value when the macro 
expansion is complete. 


This example defines a macro named str—3. The first time the macro is 
called, the macro expansion is listed (by default). The second time the 
macro is called, the macro expansion is not listed because a .mnolist direc- 
tive was assembled. The third time the macro is called, the macro expansion 
is again listed because a .mlist directive was assembled. 


str—3 SMACRO parml,parm2,parm3 
SSEring :parml:,:parm2:,:parm3: 
SEND 
StUr-=3 "red","“green", "blue" 
67646572 .string "rea", "qreen", "blue" 
6E656572 
65756C62 
-mnolist 
str—3 "Socrates","Plato","Aristotle" 
-mlist 
str—3 "Huron","Superior","Michigan" 
6F727548 .-string "Huron","Superior","Michigan" 
7075536E 
6F697265 
63694D72 
61676968 
OOOOQOO06E 


Select Listing Options option 


Syntax 


Description 


Example 


option option list 


The .option directive selects several options for the assembler output listing. 
The option /ist is a list of options separated by commas; each option selects 
a listing feature. Valid options include: 


Limit the listing of .byte directives to one line. 

Reset the B, H, L, M, and T options. 

Limit the listing of .hword directives to one line. 

Limit the listing of .long, .int, and word directives to one line. 
Limit the listing for a macro expansion to a single line. 

Limit the listing of .string directives to one line. 

Produce a symbol cross-reference listing. 


xjASr-xiring8 


Options are not case sensitive. 


This example limits the listings of the .byte, .hword, .long, .word, .int, and 
string directives to one line each. 


0001 KRRERKEKRKKEKRKRKEKKRREKERKKRRKEKRRERRKEKKEKRERKRKERRREEHK 
0002 . * Limit the listing of -byte, .-hword, * 
0003 * int, .word, .long, and .string * 
0004 * directives to one line each * 
0005 KREKEKKEKREKERRREREKKERERKERRKKRERRKRKRRRKKRKRKRKKRREE SE 
0006 .option B,H,L,T 
0007 000000 OOOOOOBD -byte =O" -OBON 75 
0008 000003 OQO000002E -hword 56q,OAAAAh 
00093 000005 AABBCCDD -long OAABBCCDDh,536+'A' 
0010 000007 OOOO15AA .word 5546,78h 
0011 000009 00000015 ont 010101b,356g,85 
0012 O0000C 65747845 .string "Extended Registers" 
rs KKEEKEKEKKKKKRRERERKKKRKRKRAKKERRKRKRKRERREKKRKKEKE 
0015 5 Reset the listing options * 
0005 REE KKRKRRKKREREKRKERERERKREREKRKREKKEKEKKKEKRKEKREKK 
0017 OO00011 -option F 
0018 000011 OOOOOO0OBD .byte -'C',OBOh,5 
000012 OOO000B0 
000013 00000005 
0019 000014 O000002E -hword 56q, OAAAAn 
000015 OOOOAAAA 
0020 000016 AABBCCDD .long OAABBCCDDh,536+'A' 
000017 00000259 
0021 000018 OOO0O1LS5AA .word 5546,78h 
000019 00000078 
0022 OOO001A 00000015 sant 010101b,356q,85 


00001B OQOOOOEE 
00001C 00000055 
0023 O00001D 65747845 .string "Extended Registers" 
OOOO1E 6465646E 
OOOO1F 67655220 
000020 65747369 
000021 00007372 
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.page | Eject Page in Listing . 


Syntax .page 


Description The .page directive produces a page eject in the listing file. The source 
statement is not printed in the source listing, but the line counter is incre- 
mented. Using the .page directive to divide a source listing into logical di- 
visions improves program readability. 


Example This example causes the assembler to begin a new page of the source list- 
ing. : 


Source file: 


-title "kA*** An example of the .page directive ****" 

.string "Page 1" 

-page ; The directive won't be printed 

.string "Page 2" 

Listing file: 

TMS320C30 Assembler Version 1.00, 87.089 Thu May 28 14:51:38 1987 
(c) Copyright 1987, Texas Instruments Inc. 
**** An example of the .page directive **** PAGE 1 
0002 000000 65676150 .string "Page 1" 

000001 00003120 . 
TMS320C30 Assembler Version 1.00, 87.089 Thu May 28 14:51:38 1987 
(c) Copyright 1987, Texas Instruments Inc. 

*x**kk¥* An example of the .page directive **** PAGE 2... 
0004 000002 65676150 -string: "Page 2". 


000003 00003220 
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Assemble into Named Section sect 


Syntax 


Description 


Example 


0001 
0002 
0003 
0004 
0005 
0006 
0007 
0008 
0009 
0010 
0011 
0012 
0013 
0014 
0015 
0016 
0017 
0018 
0019 
0020 
0021 


0022 
0023 
0024 
0025 
0026 
0027 
0028 


000000 
000000 
000001 


000000 
000000 
000001 
000002 


000000 
000002 
000003 
000004 


000003 
000003 


sect “section name” 


The .sect directive defines named sections that are used like the default .text 
and .data sections. The .sect directive begins assembling source code into 
the named section. Named sections can be used for data or code that must 
be allocated into memory separately from .text or .data. 


The section name identifies a section that the assembler assembles code 
into. The name is significant to 8 characters and must be enclosed in dou- 
ble quotes. 


Note that the .asect directive is similar to the .sect directive; however, .asect 
creates a named section that has abso/ute addresses. \|f you use the .asect 
directive to define an absolute named section, you can use the .sect direc- 
tive later in the program to continue assembling code into the absolute 
section. 


Section 3 provides additional information about named sections. 


This example defines a section, Sym_Defs, and assembles code into it. 


RREKKEKERKRRERKEKEKREREREKEKREKRERERREREREKRRERKRRRRRKKRRKRKRES 


sil Begin assembling into .text section ied 
RREKKEEKKEEKRKERKERERKERERERREKREEKRRRKREKRKREKKKRKEREKRKKRERERE 
-text 
07020001 LDF R1,R2 ; Assembled into .text 
07040003 LDF R3,R4 ; Assembled into .text 
KREKEKRKEKEKKERKREKRREREKERERERKRRKERERKEKRKRREKREKRKREKRKERRKREKKERE 
pas Begin assembling into Sym-Defs section baad 
KRKEKEKKEKEEEKERKRKEKEREKEREREKRERKKREKREKRKERERKEKRKKAKRKKKRKRKKKRKEE 
-sect "Sym_Defs" 
O148F5C2 float 3.14 
OOOOOOOF -hword OFh 
07060005 LDF R5,R6 ; Assembled into Sym—Defs 
BREKKEKKEKRKEKREKERERERKKREERKERREKREKKRKREKRKEEKEKRKEKRKRKKRRKREKRESE 
=e Resume assembling into .text section ee 
KREKRKEKRERRKRKEKKEKREKREKERKRREKRKERERERRERREKRRKKRKRKKRRKRKERKRKR ARES 
- text 
O80A0009 LDI AR1,AR2 ; Assembled into .text 
00000003 -byte 3,4 
00000004 
RKREKEREKRRKEKEKRKEKKERERKRREKERKEKEKKRERREKEKERREKRERKRERKRKRRERRRRE RES 
sd Resume assembling into Sym—Defs section =e 
KREKKEKEEKRKEKREKREKRKEEREKREKERKKEKREKRRREKRREREKRKRERERREEKEER 
-sect "Sym—Defs" 
AABBCCDD . long Oaabbccddh 
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set 


Define Assembly-Time Constant 


Syntax 


Description 


Example 
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symbol .set value 


The .set directive assigns a value to a symbol. The symbol can then be used 
in place of the value in source statements. This allows you to equate 
meaningful names with constants, registers, and other values. 


@ The symbo/ must appear in the label field. 


@ The va/ue must be a well-defined expression; that is, all symbols in the 
expression must be previously defined in the current source module. 


Undefined external symbols and symbols that are defined later in the mod- 
ule cannot be used in the expression. If the expression is relocatable, the 
symbol to which It is assigned is also relocatable. 


The value of the expression appears in the object field of the listing. This 
value is not part of the actual object code and is not written to the output 
file. 


This example shows how symbols can be assigned with .set. 


0001 KKK KKK RE KKK ERK RE KER KKK REKR ERR RE KER 
0002 ne Equate symbol FP to register dhs 
0003 ae AR3 and use it instead of the ** 
0004 wild register x 
0005 KEEKKKEKKREKEKRRERREKRKRRERREKRKERKEKEKKERERKKKRKEESE 
0006 OOOOO000B FP .set AR3 
0007 000000 0840C300 LDI *FP,RO 

O08 
pice KRREKRKEKKERRREREKRREKRERRKRERKERERRKERKKRRKRKRKRRREE 
OO10 * ** Set symbol count to an integer ** 
OO11 ** expression and use it.as an iia 
0012 ** immediate operand xe 
0013 KEKKKRKEEKKEKEREKREKRRKEKREKRERKKEKERKRKEKKEKKRKEKEER 
0014 00000035 count -set 100/2 + 3 
0015 000001 08600035 LDI count ,RO 
0016 
ae KRKEREEKEKREREKREERRKEKKEKREEKRKEKRKRKRRKRKRRRRRKRRKKEK 
0018 balled Set symbol symtab to a relo- -* 
0019 ** catable expression and use it ** 
0020 islaed as a relocatable operand ‘aad 
0021 KREEKKEKKREKREKREKREEKKREKKREKREKEREKKKEKKKEKRREEHE 
0022 000002 OQOOO0000A label .word 10 
0023 00000003' symtab .set label+l 
oe 000003 08200003+ LDI @symtab,RO 
Bose KREEKKKEKKRERREREKEKEEKRKERERKEKKEKKREKKEKEREEER HE 
0027 ** . Set symbol PI to a floating- ye 
0028 *% point constant and use it as lees 
0029 oe an operand ** 
0030 KAKKEKRREKRRKRKERKEKRERERRRRKRKEKRRRKRREKRRRKEKREEK 
0031 O1490FCF PI -set 3.14159 
0032 000004 O1490FCF -float PI 
0033 | 
ew KEREKRRERKRRRKEKRKERREREERERRKEREKEKEKRKEREEEESE 
0035 dl Set symbol nsyms equal to the ** 
0036 =e symbol count and use it as you ** 
0037 on would use count oe 
0038 KREEKRKEKEEKRKERKRERRERKEREKRKREKKREKRKKEKERRREKRESR 
0039 00000035 nsyms .set count 
0040 000005 08600035 LDI nsyms,RO 


Reserve Space space 


Syntax space s/ze in words 


Description The .space directive reserves size number of words in the current section 
and fills them with Os. The section program counter is incremented to point 
to the word following the reserved space. 


The .space directive is equivalent to s/ze number of .word O directives. 


Example This example reserves 100 Q-filled words in the .text section. Note that the 
SPC equals 03h before the .space directive is assembled; after the .space 
directive is assembled, the SPC is incremented to equal 067h. 


OOO0O1 RREKREKEKRKEKEKKEKRKKEKEKKKRKRKEKRKRKEKKRKKRARKKKIE KKK KAK ESE 
0002 * Begin assembling into .text * 
0003 KREKKKEKKKEKREKKEKEKKER KKK KKK KEKKEKRAEKKEKKKRKR EK 
0004 O00000 text 
0005 OO00C0O00 OOOOOOCOA .word OAh, OBh 

000001 OOOOOOCOB 
0006 000002 00004230 .string "ARO" 
0007 KEKE KKRKRKKEKKKKKRKKEKK RE KEKE K KEKE KKKRKKEKEE 
0008 * Reserve a block of 100 words in .text * 
0009 KHEKEKRKKKEKEKREKRKKE EKER KEKE REKRKEKKEKEKAKKRKAREEKE 
0010 000003 OO0O00000 Sp—X: .space 100 
0011 000067 OOO0O0000C .word OCh - Stili. in. «text 
0012 000068 00000003' .word Sp—X 


text section 
Oh -9000000A 


3h 


‘boo ee 
_reserved - S 


-yuyyuug | 


Figure 5-12. An Example of the .space Directive 
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string Initialize Text 


Syntax 


Description 


Example 


O001 
0002 
0003 


0004 
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000000 
000001 
000002 
000003 
000004 


string “string;” [..... “stringy” ] 


The .string directive places 8-bit characters from a character string into the 
current section. The data is packed so that each word contains four 8-bit 
values. Each string is either: 


@ An expression which the assembler will evaluate and treat as a 32-bit 
signed number. 


@ A character string enclosed in double quotes. Each character repres- 
ents a separate value. 


Values are packed into words starting with the least significant byte of the 
word and moving toward the most significant portion as more bytes are 
added. Any unused space is padded with null bytes (Qs). 


The assembler truncates any values that are greater than 8 bits. You may 
have up to 100 operands, but they must fit on a single source statement 
line. 


If you use a label, it points to the first word that is initialized. 


This example places &-bit values into words in the current section. 


44434241 Str.3% .string "ABCD" 

54535251 .string 5lh, 52h, 53h, 54h 
73756F48 .string "Houston" 

OO6E6F74 

00000030 .string 36 + 12 


Assemble into .text Section text 


Syntax 


Description 


Example 


text 


The .text directive tells the assembler to begin assembling into the .text 
section, which normally contains executable code. The section program 
counter is set to 0 if nothing has yet been assembled into the .text section. 
If code has already been assembied into the .text section, the section pro- 
gram counter is restored to its previous value in the section. 


Note that the assembler assumes that .text is the default section. Therefore, 
at the beginning of an assembly, the assembler assembles code into the 
.text section unless you specify one of the other initialized-section direc- 
tives (.data, .sect, or .asect). 


For more information about COFF sections, see Section 3. 


This example assembles code into the .text and .data sections. The .text 
section contains bytes 1, 2, 3, and 4, and the .data section contains bytes 
5,6, 7, and 8. 


OOO] KRREKRKKEKKEKKEKREKRKERKRKRKKRRKEKRERKEKRKRERKREKRKRRKEKREEE 
0002 ** Begin assembling into .data section ** 
00038 KRKKEKRKKEKEKEKREKKREREKRERREKEKEKKEREEKEREKEREREREE 
0004 O00000 .data 
0005 000000 00000005 .byte 56 

000001 OO0000006 
0006 
O007 KRKEREKRKKRKEKRKEKRKEKREKRKEKRKREERKKEEEKKEERKKREKEKERREREKKKEESR 
0008 ** Begin assembling into .text section ** 
0009 KERRKKEKRKRERKRKERERKEKEREKREKRERKRKEKKRREKKERKEKEE 
0010 O00000 .text 
OO011 000000 00000001 .byte i 
0012 000001 00000002 .byte 2¢2 

000002 00000003 
0013 
0014 KRREKKRKEKEKRKEKRKKREKRRKEKRKKEKKKRKEKREEKREKRREKERKERKEE 
0015 ** Resume assembling into .data ** 
0016 KEEARKEKEEKRKEEKRKKEKKEKRREKREKRREEKREKEKREKEREKRKEKERER 
0017 000002 .data 
0018 000002 00000007 .byte 7,8 

000003 00000008 
0019 
0020 KEREREKEKERKEKERKKRKEKRKKREKRKRKRKREREKEKRKAKKERRKRRKKRRKEK 
0027 ae Resume assembling into .text sc) 
0022 KKK KKK KKK KKK KKK KEKE KEK KKK KEKE KKK KKK KEE KEKE 
0023 000003 .text 
0024 000003 00000004 .byte 4 
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title 


Define Page Title 


Syntax title “sizing” 

Description _ The .title directive supplies a title that is printed in the heading on each 

listing page. The source statement itself is not printed, but the line counter 
is incremented. The string is a quote-enclosed title of up to 50 characters. 
If you supply more than 50 characters, the assembler truncates the string 
and issues a warning. 
The assembler prints the title on the page that follows the directive, and on 
subsequent pages until another .title directive is processed. If you want a 
title on the first page of a listing, then the first source statement must con- 
tain a .titie directive. 

Example This example prints the title *** Floating Point Routines *** in the 
page headings of the source listing. 

Source statement: 
.title "*k* Floating Point Routines ***" 
Listing file: 
TMS320C30 Assembler Version 1.00, 87.089 Tue Apr 21 11:39:03 198 
(c) Copyright 1987, Texas Instruments Inc. 

x**x* Floating Point Routines *** PAGE 1. 
TMS320C30 Assembler Version 1.00, 87.089 Tue Apr 21 11:39:03 198 
(c) Copyright 1987, Texas Instruments Inc. 

*¥** Floating Point Routines *** PAGE 2 
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Reserve Uninitialized Space .usect 


Syntax 


Description 


Example 


symbol .usect “section name”, size in words 


The .usect directive reserves space for variables in an uninitialized, named 
section. This directive is similar to the .bss directive; both simply reserve 
space for data and have no contents. However, .usect defines additional 
sections that can be placed anywhere in memory, independently of the .bss 
section. 


® The symbo/ points to the first location reserved by this invocation of 
the .usect directive. The symbo/ corresponds to the name of the var- 
iable that you’re reserving space for. 


@ The section name must be enclosed in double quotes; only the first 8 
characters are significant. This parameter names the uninitialized 
section. 


® The size is an expression that defines the number of words that will 
be reserved in section name. 


Other sections directives (.text, .data, .sect, and .asect) end the current 
section and tell the assembler to begin assembling into another section. 
The .usect and .bss directives, however, do not affect the current section. 
The assembler assembles the .usect and the .bss directives and then re- 
sumes assembling into the current section. 


You can repeat the .usect directive to define more than one variable in the 
specified section. Variables which can be located contiguously in memory 
can be defined in the same section by using multiple .usect directives with 
the same section name. 


For more information about COFF sections, see Section 3. 


This example uses the .usect directive to define two uninitialized, named 
sections, varl and var2. The symbol ptr points to the first word reserved 
in the varl1 section. The symbol axyray points to the first word in a block 
of 100 words reserved in varl, and dflag points to the first word in a 
block of 50 words in vari. The symbol vec points to the first word re- 
served in the var2 section. 


Figure 5-13 shows how this example reserves space in two uninitialized 
sections, varl and var2. 
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.usect Reserve Uninitialized Space 

OOOl1 KKK RRR RRAKRRERIEE 
0002 * Assemble into .text * 
0003 KREEKREEKREKKEKKREKREKRKEEKRKERRE RRR ERREREKEREEE 
0004 000000 text 
0005 000000 08010000 LDI RO,R1L 
0006 
0007 KERERKKEKKEKREKKRKRKKERKRREKRKKRRKRREKRRRREESE 
0008 * Reserve 1 word in varl * 
0009 KIER EKKEKE KKK KEKE RRR KEKE EEE 
0010 000000 ptr -usect "varl", 1 
O0O11 
0012 KKEKRKRKKKRKRKRARRKKREKKRKEKREKRRKRARKRARKKAKRAEKESK 
0013 * Reserve 100 more words in varl * 
0014 RKREKRKEKRKREEKKEREKRREREKRKREKRKREKEKKEKEREKEREEKE 
0015 QOO0001 array -usect "“varl", 100 
0016 
0017 000001 08020001 LDI R1,R2 -- Stata: ni 
0018 
0019 KERR KEKKRREKKEKRKKERKE KERR KARKRKRKRKEK 
0020 * Reserve 50 more words in varl * 
O021 KERR KEKE REE RRR RRA 
0022 000002 dflag -usect "varl", 50 
0023 
0024 000002 08030002 LDI R2,R3 ; Still in 
0025 
0026 RREEKRKKRKREKKKEKRRKERERREKRKE KER KEKE KRAEEERSE 
0027 * Reserve 100 words in var2 * 
0028 KREKKKEKKREKE KERR KEK KKKKRRKKRREKRKREKKRREKSE 
0029 000000 vec -usect "“var2", 100 
0030 
0031 000003 08200000 LDI @vec,RO * SEL. in 
0032 
0033 KRKEEKEKRRKEKRKRKRRKEREKRERKRRE RRR RAKE RE 
0034 * Declare an external .usect symbol * 
0035 BKEREKKKRKRKKRRER ERR KER RKRKRKRKKRRRKKRKRKR RRA KSE 
0036 «glopal array 

Section vari Section var2 

ptr vec 
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array 


dflag 


100 words 


100 words 


50 words 


151 words reserved in var1 


Figure 5-13. An Example of the .usect Directive 


100 words reserved in var2 


Section 6 


Instruction Set 


The TMS320C30 supports a base set of general-purpose instructions as well 
as arithmetic-intensive instructions that are particularly suited for digital signal 
processing and other numeric-intensive applications. 


This section does not cover topics such as opcodes or instruction timing; the 
Third-Generation TMS320 User's Guide discusses the instruction set in detail. 
The Third-Generation TMS320 User's Guide also contains an alphabetical 
presentation which is similar to the directives reference that begins on page 
5-13. 


This section provides a general summary of the TMS320C30 instruction set: 


® Section 6.1 lists the syntax, operation, and description of each in- 
struction. 


e@ Section 6.2 and Section 6.3 summarize and describe optional syntaxes 
of three-operand instructions and parallel instructions, respectively. 


@ Section 6.4 through Section 6.8 describe the functional categories of the 
instruction set. 
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Instruction Set - Summary 


6.1 Summary 


Section 6.1.4 lists the TMS320C30 instruction set alphabetically. Each table 
entry shows the instruction’s syntax and operation, contains a brief de- 
scription, and shows any optional syntaxes. The key for Section 6.1.4 lists the 
valid addressing modes that can be used for various operands. Section 6.1.1 
summarizes these addressing modes, Section 6.1.2 summarizes the optional 
syntaxes, and Section 6.1.3 summarizes the condition codes used with con- 
ditional instructions. Section 6.1.4 begins on page 6-5. 


6.1.1 Addressing Modes 
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The Third-Generation TMS320 User's Guide discusses addressing modes in 
detail. This section summarizes the addressing modes mentioned in Section 
6.1.4. 


@ General addressing modes: 


Register mode: The operand is a CPU register. For floating-point 
operations, use an extended register (RO-R7). For integer operations, 
use any register. 


Short immediate mode: The operand is a 16-bit immediate value. 
Short immediate operands may be sigried integers, unsigned integers, 
or floating-point values, depending on the instruction. 


Direct mode: The operand is the contents of a 24-bit address, specified 
by @addr. The 8 MSBs of the address are specified by the DP register; 
the 16 LSBs are specified by the instruction word. (You can use the 
LDP aaah to load the page number into the data page pointer re- 
gister. 


indirect mode: An auxiliary register indicates the address of the oper- 
and. Table 6-1 lists the various forms that indirect operands may take. 
The displacement may be specified as a value from 0-255 or as one of 
the index registers (IRO or IR1). 


It is not necessary to specify the displacement if it is 1, because the as- 
sembler assumes a default displacement of 1. For example, *++ARn is 
equivalent to *++ARn(1) 


e Three-operand addressing modes: 
Register mode: Same as for general addressing modes. 


Indirect mode: Same as for general addressing modes, except the dis- 
placement is limited to 0, 1, [RO, or [R1. 


@ Parallel addressing mode: 


Register mode: The operand is an extended register (RO-R7). In some 
cases, only RO/R1 or R2/R3 can be used as an operand. 


Indirect mode: Same as for general addressing modes, except the dis- 
placement is limited to 0, 1, IRO, or IR1. 


®@ Long-immediate addressing mode: 


The operand is a 24-bit immediate value (usually specified by a label). 
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@ Conditional branch addressing mode: 


Register mode: Same as for general addressing modes; the contents 
of the register are loaded into the PC. 


PC-relative mode: A signed 16-bit displacement is added to the PC. 
The destination address is usually specified as a label; the assembler 
calculates the displacement. 


Table 6-1. Indirect Addressing Mode 


[ARn | Indirect withno displacement. ——SOSCSC~C~—SCSCSCSCSCS 


|*ARn++(IRO)B | _ Indirect with postindex (IRO) and bit-reversed modification 


T Optional circular modification (specified by %) 


6.1.2 Optional Syntaxes 


The assembler allows a relaxed syntax form for several instructions. These 
optional forms simplify the assembly language so that you can ignore spe- 
cial-case syntax for some instructions. 


@ If the source and destination register are the same, you need only specify 
the register once. Instructions that can use this optional syntax include: 
ABSF FIX NEGB NEGI NOT 
ABSI FLOAT NEGF NORM RND 
For example, 

ABSI RO,RO can be written as ABSI RO 


@ You can omit the displacement for indirect operands; the assembler will 
assume a displacement of 1. Instructions that use general addressing 
modes, three-operand addressing modes, or parallel addressing modes 
may have indirect address operands. For example, 


LDI *ARO++(1),RO can be written as LDI *ARO++,RO 


®@ Long-immediate mode operands can be written with an @ symbol. The 
branch and call instructions can use this optional syntax. For example, 


BR label can be written as BR @label 
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6.1.3 Condition Codes 


The TMS320C30 supports conditional loads, branches, traps, calls, and re- 
turns. These instructions use the condition codes in Table 6-2. 


Takkle 6-2. Condition Codes 


Unconditional. Compares 


|Cond.| Code | Description | Flags _ 


Unsigned Compares 


Cond.| Code | Description | Flags _ 


Lower than C 
Lower or same _C OR Z_| 
Higher than CAND Z 
Higher or same ¢ 
Equal Zz 

Not equal Z 


Signed Compares 


Less than N 
Less than or equal _N OR Z_| 
Greater than N AND Z 


Greater than or equal 
Equal 
Not equal 


Compare to Zero 


NIN Z| 


Zero 
Not zero 
Positive 
Negative 
Nonnegative 


Nonnegative 
Negative 
Nonzero 
Zero 

No overflow 
Overflow 
No underflow 

Underflow 

No carry 

Carry 

No latched overflow 

Latched overflow 

No latched floating-point underflow 
Latched floating-point underflow 
Zero or floating-point underflow 


N 
N 
Z 
Z 
V 
as 
UF 
UF 
C 
Cc 
LV 
LV 
LUF 
LUF 
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6.1.4 Instruction Set Summary Table 


| ABSF Sre,An Absolute Value of a Floating-Point Number 
[ABSF An] Operation: |Src| ~ Rn 


Load the absolute value of a floating-point number into an extended- 
precision register. 


ABSI Src,Dreg Absolute Value of an Integer 
[ABSI Dreg] Operation: |Src| ~ Dreg 
Load the absolute value of an integer into a register. 


ADDC Src,Dreg Add Integers with Carry 
Operation: Src + Dreg + C > Dreg 


Add the source, the contents of the destination register, and the carry bit 
together, and store the sum in the destination register. The operands are 
signed integers. 


ADDC3 Src?7,Src2,Dreg | Add Integers with Carry (3-Operand) 
fADDC Src7,Src2,Dreg| | Operation: Srct1 + Src2 + C > Dreg 


Add the two source operands and the carry bit together, and store the sum 
in the destination register. The operands are signed integers. 


ADDF Src,An Add Floating-Point Values 
Operation: Src + Rn > Rn 


| Add the source operand to the contents of an extended-precision register, 
and store the sum into the register. The operands are floating-point num- 
bers. 


ADDF3 Src7,Src2,Rn Add Floating-Point Values (3-Operand) 
[ADDF Sre7,Sre2,Rn) Operation: Src1 + Src2 > Rn 


Add the two source operands together and store the sum in the destination 
register. The operands are floating-point numbers. 


ADDI Src,Dreg Add Integers 
Operation: Src + Dreg ~ Dreg 


Add the source operand to the contents of the destination register and store | 
the sum in the destination register. The operands are signed integers. 


Add Integers (3-Operand) 
Operation: Srci + Src2 > Dreg 


ADDI3 Srce7,Src2,Dreg 
| [ADDI Src7,Srce2,Dreg] 


Add the two source operands together and store the sum in the destination 
register. The operands are signed integers. 


Note: Optional syntaxes are shown in [brackets]. 


Key: 

Src -— General addressing modes Dreg -— Register mode (any register) 
Src1 -— Three-operand addressing modes Rn ~ Register mode (RO-R7) 

Src2 - Three-operand addressing modes Daddr — Destination memory address 
Csrce -.Conditional branch addressing modes ARn-~ -— Auxiliary register n (ARO-AR7) 
Sreg -— Register mode (any register) Addr — 24-bit immediate address (label) 


Count — Shift value (general addressing modes) Cond -— Condition code (see Table 6-2, pg. 6-4) 
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ANDS3 Src7,Srce2,Dreg Bitwise Logical AND (3-Operand) 
[AND Src7,Srce2,Dreg] Operation: Src1 AND Src2 > Dreg 


Perform a bitwise logical AND of the two source operands and store 
the result in the destination register. All the operands are unsigned 
integers. 


ANDN Src,Dreg Bitwise Logical AND with Complement 
Operation: Dreg AND “Src > Dreg 


Perform a bitwise logical AND of the destination register and the bit- 
wise logical complement of the source operand, and store the result 
into the destination register. Both operands are unsigned integers. 


Bitwise Logical ANDN (3-Operand) 
Operation: Srct AND 7E Src2 > Dreg 


ANDN3 Src7,Src2,Dreg 
[ANDN Src7,Src2,Dreg] 


Perform a bitwise logical AND of source operand 1 and the bitwise 
logical complement of the source operand 2, and store the result into 
the destination register. All the operands are unsigned integers. 


ASH Count,Dreg Arithmetic Shift 


| Operation: If Count > 0 
Dreg << Count > Dreg 
Else 
Dreg >> |Count| ~ Dreg 


If Count is greater than or equal to 0, left shift the contents of the | 
destination register by Count. Low-order bits are filled with Os, and 
high-order bits are shifted out through the carry bit. 


lf Count is less than 0, right shift the contents of the destination reg- 
ister by the absolute value of Count. WHigh-order bits are sign ex | 
tended, and low-order bits are shifted out through the carry bit. 


Both operands are signed integers. 
ASH3 Count,Src,Dreg Arithmetic Shift (3-Operand) 


[ASH Count,Src,Dreg] Operation: If Count > 0 
Src << Count ~ Dreg 
Else 
Sre >> |Count| > Dreg 


If Count is greater than or equal: to O, left shift the source operand by 
Count. Low-order bits will be filled with Os, and high-order bits are 
shifted out through the carry bit. 


lf Count is less than 0, right shift the contents of the destination reg- 
ister by the absolute value of Count. High-order bits are sign ex- 
tended, and low-order bits are shifted out through the carry bit. 


The shifted value is stored in the destination register. Both operands 
are signed integers. 


Bcond Csrc Branch Conditionally (standard) 


[Beond @Csrc] 


Operation: If cond = true 
If Csrc is a register, Csrc —~ PC | 
lf Csrc is an immediate value, Csrc + PC + 1 7 PC 
Else 
continue 


Perform a branch if the condition is true. If Csrc is a register or a label, 
its contents are loaded into the PC. If Csrc is a 16-bit immediate value, 
it is added to the PC. You can precede labels with an @ symbol. 
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BcondD Csrc Branch Conditionally (delayed) 


[BeondD @Csrc] Operation: If cond = true 
lf Csrc is a register, Csrc > PC 
If Csrc is an immediate value, Csrc + PC + 3 > PC 
Else 
continue 


Perform a branch if the condition is true. If Csrc is a register or a label, its 
contents are loaded into the PC. If Csrc is a 16-bit immediate value, it is 
added to the PC. You can precede labels with an @ symbol. 


BR Addr Branch Unconditionally (standard) 
[BR @Adar] Operation: Addr ~ PC 


Perform an unconditional branch. The source operand is a label or a 24-bit 
unsigned immediate value. If the D is specified, the branch is delayed. If 
the operand is a label, you can precede it with an @ symbol. 


BRD Addr Branch Unconditionally (delayed) 
[BRD @Addadr] Operation: Addr ~ PC 


Perform an unconditional branch. The source operand is a label or a 24-bit 
unsigned immediate value. If the D is specified, the branch is delayed. If 
the operand is a label, you can precede it with an @ symbol. 


CALL Addr Cal! Subroutine 


[CALL @Adar] Operation: Next PC > *++SP 
Addr > PC 


Call a subroutine. If the operand is a label, you can precede it with an @ 
symbol. 


| CALLcond Csrc Call Subroutine Conditionally 


| [CALLcond @Csrc] Operation: If cond = true 
Next PC > *++SP 
If Csrc is a register, Csrc > PC 
lf Csrc is an immediate value, Csrc + PC —~ PC 
Else 
continue 


Call a subroutine if the condition is true. If Csrc is a register or a label, its 
contents are loaded into the PC. If Csrc is a 16-bit immediate value, it is 
added to the PC. You can precede labels with an @ symbol. 


CMPF Src,An Compare Floating-Point Values 
Operation: Set flags on Rn - Src 


Compare the source and destination operands by subtracting the source 
from the destination and setting the appropriate status bits. The result of 
the subtraction is not stored — this is a nondestructive compare. Both op- 
erands are floating-point numbers. 


Note: Optional syntaxes are shown in [brackets]. 


Key: 

Src —- General addressing modes Dreg -— Register mode (any register) 
Src1  —- Three-operand addressing modes Rn — Register mode (RO-R7) 

Srec2 - Three-operand addressing modes Daddr — Destination memory address 
Csrc — Conditional branch addressing modes ARn-~ — Auxiliary register n (ARO-AR7) 
Sreg -— Register mode (any register) Addr -— 24-bit immediate address (label) 


Count — Shift value (general addressing modes) Cond -— Condition code (see Table 6-2, pg. 6-4) 
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CMPF3 Src2,Src7 Compare Floating-Point Values (3-Operand) 
| [CMPF Src2,Src7] 


Operation: Set flags on Src1 - Src2 


1 Compare the two source operands by subtracting source 2 from source 1 
and setting the appropriate status bits. The result of the subtraction is not 
stored — this is a nondestructive compare. Both operands are floating-point 
numbers. : 


CMPI Src,Dreg Compare Integers 
Operation: Set flags on Dreg - Src 


Compare the source and destination operands by subtracting the source 
from the destination and setting the appropriate status bits. The result of 
the subtraction is not stored — this is a nondestructive compare. Both op- 
erands are integers. 


CMPI3 Src2,Sre7 i Compare Integers (3-Operand) 
[CMPI Src2,Src7] Operation: Set flags on Src - Src2 


Compare the two source operands by subtracting source 2 from source 1 
and setting the appropriate status bits. The result of the subtraction is not 
stored — this is a nondestructive compare. Both operands are integers. 


DBcond ARn,Csrc Decrement and Branch Conditionally (standard) 


| [DBcond Afn,@Csrc] | Operation: ARn - 1 — ARn 
If cond = true and ARn > 0 
If Csrc is a register, Csrc > PC 
If Csrc is an immediate value, Csrc + PC + 1 > PC 
Else 
continue 


Decrement the specified auxiliary register and branch if the condition is true 
and the specified auxiliary register is not zero. If Csrc is a register or a label, 
its contents are loaded into the PC. If Csrc is a 16-bit immediate value, it 
is added to the PC. You can precede labels with an @ symbol. 


DBcondD Afn,Csrc 
[DBcond ARn,@Csrc] 


Decrement and Branch Conditionally (delayed) 


Operation: ARn-1— ARn 
If cond = true and ARn > 0 
PC +3 —7 PC 
If Csrc is a register, Csrc > PC 
If Csrc is an immediate value, Csrc + PC + 3 > PC 
Else 
continue 


Decrement the specified auxiliary register and branch if the condition is true 
and the specified auxiliary register is not zero. If Csrc is a register or a label, | 
its contents are loaded into the PC. If Csrc is a 16-bit immediate value, it 
is added to the PC. You can precede labels with an @ symbol. 


FIX Src,Dreg 
[FIX Dreg] 


Convert Floating-Point Value to Integer 
Operation fix(Src) ~ Dreg 


Convert a floating-point operand to the nearest integer which is less than 
or equal to its absolute value and load the result into the destination reg- 
ister. 


FLOAT SreAn 
[FLOAT An] 


Convert Integer to Floating-Point Value 


| Operation: float(Src) — Rn 


Convert an integer into a floating-point value and load the result into an 
extended-precision register. 


Count — Shift value (general addressing modes) Cond -— Condition code (see Table 6-2, pg. 6-4) 
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Interrupt Acknowledge 


Operation: Perform a dummy read operation with IACK = 0. 
At end of dummy read, set [ACK = 1. 


Perform a dummy read operation with JACK = 0. IACK is set to 1 at the 
end of the dummy read. This instruction can be used to generate an ex- 
ternal interrupt acknowledge. 


If the specified address is off-chip the processor reads the data at that ad- 
dress. Then, the [ACK signal and the address can be used to signal an in- 


terrupt acknowledge to external devices. The data read by the processor is 
not used. 


Idle Until interrupt 


Operation: 1 — ST(GIE) 
Next PC ~ PC 
Idle until interrupt 


Load the next PC value into the PC and idle until an interrupt is received. 
When an interrupt is received, the contents of the PC are pushed onto the 
system stack. 


LDE Sre,Rn Load Floating-Point Exponent 
Co Operation: Src(exponent) ~ Rn(exponent) 
Load the exponent portion of a word into the exponent field of an ex- 
tended-precision register. 
LDF Src,An Load Floating-Point Vaiue 
Operation: Src > Rn 
Load a floating point-value into an extended-precision register. 


LDFcond Src,Rn Load Floating-Point Value Conditionally 
Operation: If cond = true 
Src > Rn 
| Else 
Rn is not changed 
If the specified condition is true, a floating-point value is loaded into an 
extended-precision register. If the condition is false, the value is not 
ioaded. 
LDFI Sre,Dreg Load Floating-Point Value, Interlocked 
Operation: Signal interlocked operation 
Src > Rn 
| The source operand is loaded into the destination register and an inter- 
locked operation is signaled over the XFO and XF1 pins. The operands are 
floating-point values. 


LDI Src,Dreg Load Integer 
Operation: Src > Dreg 


Load the contents of the source operand into a register. The source oper- 
and is a signed integer. 


Note: Optional syntaxes are shown in [brackets]. 


Key: 

Src — General addressing modes Dreg — Register mode (any register) 
Srci — Three-operand addressing modes Rn — Register mode (RO-R7) 

Src2 -— Three-operand addressing modes Daddr — Destination memory address 
Csre —-— Conditional branch addressing modes ARn-~ -— Auxiliary register n (ARO-AR7) 
Sreg — Register mode (any register) Addr - 24-bit immediate address (label) 
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Load Integer Conditionally 


LDicond Src,Dreg 


Operation: If cond = true 
Src ~ Dreg 
Else 
Dreg is not changed 


If the specified condition is true, the contents of the source operand are 
loaded into a register. The source operand is an integer. If the condition 
is false, the source operand is not loaded. 


LDII Src,Dreg Load Integer, Interlocked 


Operation: Signal interlocked operation 
Src > Dreg 


The source operand is loaded into the destination register and an inter- 
locked operation is signaled over the XFO and XF1 pins. The operands are 
signed integers. 


LDM Src,Rn 


Load Floating-Point Mantissa 
Operation: Src(mantissa) > Rn(mantissa) 

Load the mantissa portion of a word into the mantissa field of an extend- 
ed-precision register. 
Logical Shift 
Operation: If Count > 0 

Dreg << Count ~ Dreg 


Else 
Dreg >> |Count| > Dreg 


lf Count is greater than or equal to zero, left shift the contents of the des- 
tination register by Count. Low-order bits are filled with Os and high-order 
bits are shifted out through the carry bit. 


LSH Count,Dreg 


If Count is less than zero, right shift the contents of the destination register 
by the absolute value of Count. High-order bits are filled with Os and 
low-order bits are shifted out through the carry bit. 


The Count. operand is a signed integer; Dreg is an unsigned integer. 
LSH3 Count,Src,Dreg Logical Shift (3-Operand) 


[LSH Count,Src,Dreg| Operation: If Count > 0 
Src << Count > Dreg 
Else 
Src >> {Count| ~ Dreg 


lf Count is greater than or equal to zero, left shift the source operand by 
Count. Low-order bits are filled with Os and high-order bits are shifted out 
through the carry bit. The result is stored in the destination register. 


If Count is less than zero, right shift the source operand by the absolute 
value of Count. High-order bits are filled with Os and low-order bits are 
shifted out through the carry bit. 


The Count operand is a signed integer; Src is an unsigned integer. The 
result is stored in the destination register. 


MPYF Src,Rn Multiply Floating-Point Values 


Operation: Src x Rn ~ Rn 


Multiply the source operand by the contents of an extended-precision re- 
gister and store the result into the register. Both operands are floating- 
point numbers. 
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MPYF3 Src7,Src2,Rn Multiply Floating-Point Values (3-Operand) 
[MPYF Src7,Src2,Rn] Operation: Srct1 x Src2 — Rn 


Multiply the two source operands together and store the result into the 
extended-precision register. All the operands are floating-point numbers. 


Multiply Integers 


MPYI Src,Dreg 
Operation: Src x Dreg > Dreg 


Multiply the source operand by the contents of the destination register and 
store the result in the register. Both operands are 24-bit signed integers; 
the result is the 32 LSBs of the product. 


Multiply Integers (3-Operand) 


MPYI3 Src7,Src2,Dreg 
[MPYI Src7,Src2,Dreg] | Operation: Srci x Src2 ~ Dreg 


Multiply the two source operands and store the result in the register. All 
the operands are 24-bit signed integers; the result is the 32 LSBs of the 
product. 


Negate Integer with Borrow 


NEGB Src,Dreg 
[NEGB Dreg] 


Operation: O- Src - C > Dreg 


Load the difference between the source operand, O, and the carry bit into 
the destination register. The operands are signed integers. 


Negate Floating-Point Vaiue 


NEGF Src,Rn 
[NEGF Rn] Operation: O- Src > Rn 


Load the difference between the source operand and 0 into the extend- 
ed-precision register. The operands are floating-point numbers. 


Negate Integer 


NEGI Src,Dreg 
[NEGI Dreg] Operation: O- Src ~ Dreg 


Load the difference between the source operand and 0 into the destination 
register. The operands are signed integers. 


No Operation 


NOP 


| [NOP Src] Operation: No ALU or multiplier operations. 


ARn is modified if Src is specified in indirect mode. 


Modify the source operand (if specified), or perform no operation. Src 
must be an indirect operand. 


Normalize Floating-Point Value 


NORM Src,ARn 
[NORM Rn] Operation: normalize(Src) > Rn 


Normalize a floating-point number and load the result into an extended- 
precision register. 


Bitwise Logical Complement 


| NOT Src,Dreg 
[NOT Dreg] Operation: Src > Dreg 


Load the bitwise logical complement of the source operand into the desti- 
nation register. 


Note: Optional syntaxes are shown in [brackets]. 


Key: 

Src -— General addressing modes Dreg -— Register mode (any register) 
Src1 — Three-operand addressing modes Rn ~ Register mode (RO-R7) 

Src2 -— Three-operand addressing modes Daddr — Destination memory address 
Csrc — Conditional branch addressing modes ARn~ — Auxiliary register n (ARO-AR7) 
Sreg -— Register mode (any register) Addr — 24-bit immediate address (label) 


Count — Shift value (general addressing modes) Cond -— Condition code (see Table 6-2, pg. 6-4) 
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SS 


OR Src,Dreg Bitwise Logical OR 
Operation: Dreg OR Src > Dreg 
Load the bitwise logical OR of the source and the destination into the 
destination register. The operands are unsigned integers. 


OR3 Src7,Src2,Dreg Bitwise Logical OR (3-Operand) 
[OR Sre7,Src2,Dreg] Operation: Src1 OR Src2 — Dreg 


Load the bitwise logical OR of the two source operands into the destina- 
tion register. The operands are unsigned integers. 


POP Dreg Pop Integer from Stack 
Operation: *SP-- > Dreg 
Pop the contents of the top of the system stack into the destination register. 
The value popped from the stack is an integer. 


Pop Floating-Point Value from Stack 


Operation: *SP-- — Rn 
Pop the contents of the top of the system stack into an extended-precision 


POPF An 
ae register. The value popped from the stack is a floating-point number. 
PUSH Sreg Push Integer on Stack 
Operation: Sreg ~ *++SP 
Push the contents of the source register onto the top of the system stack. 
| The value pushed on the stack is an integer. 
Push Floating-Point Value on Stack 


RETicond Return from Interrupt Conditionally or Unconditionally 


Operation: Rn ~ *++SP 


Push the contents of an extended-precision register onto the top of the 
system stack. The value pushed on the stack is a floating-point number. 


[RETH Operation: If cond = true 
*SP-- > PC 
1 — ST(GIE) 
Else 
continue 


Perform a return from an interrupt routine. If the condition is true or if there 
is no condition, pop the top of the system stack into the PC and set the 
global interrupt enable bit to 7. 


RETScond Return from Subroutine Conditionally or Unconditionally 


[RETS] 


Operation: If cond = true 


*SP-- > PC 
Else 
continue 


Perform a return from a subroutine. If the condition is true or missing, pop 
the top of the system stack into the PC. 


RND Src,An Round Floating-Point Value 
[RND An] Operation: round(Src) ~ Rn 


Round the source operand to the nearest single-precision floating-point 
number and load it into an extended-precision register. 


Instruction Set - Summary 


ROL Dreg Rotate Left 


Operation: Dreg rotated left 1 bit > Dreg 
ROLC Dreg 
ROR Dreg 


| RORC Dreg 
RPTB Va/ 


RPTS Va/ 


Note: Optional syntaxes are shown in [brackets]. 


Rotate the contents of the destination register left one bit and store the 
result back into the destination register. The carry bit is set to the original 
value of the MSB. 


Rotate Left through Carry 
Operation: Dreg rotated left 1 bit through carry ~ Dreg 


Rotate the contents of the destination register left one bit through the carry 
bit and store the result back into the destination register. The carry bit is 
set to the original value of the MSB and the new LSB value is set to the 
original value of the carry bit. 


Rotate Right 
Operation: Dreg right-rotated 1 bit through carry bit ~ Dreg 


Rotate the contents of the destination register right one bit and store the 
result back into the destination register. The carry bit is set to the original 
value of the LSB. 


Rotate Right through Carry 
Operation: Dreg rotated right 1 bit through carry ~ Dreg 


Rotate the contents of the destination register right one bit through the 
carry bit and store the result back into the destination register. The carry 
bit is set to the original value of the LSB and the new MSB value is set to 
the original value of the carry bit. 


Repeat Block of Instructions 


Operation: Val ~ RE 
1 > ST(RM) 
next PC —~ RS 


Repeat a block of instructions by the number in the RC (repeat count) re- 
gister. Val is a 24-bit immediate value that is loaded into the repeat end 
address (RE) register. The RM (repeat mode) status bit is set to 1, and the 
address of the next instruction is loaded into the repeat start address (RS) 
register. 


Repeat Single Instruction 


Operation: Val ~ RC 
1 > ST(RM) 
next PC —~ RSA 
next PC — REA 


Repeat a single instruction by the number in the RC (repeat count) register. 
Val is a 24-bit immediate value that is loaded into the RC (repeat counter) 
register. The RM (repeat mode) and RS (repeat single) status bits are set 
to 1, and the address of the next instruction is loaded into the repeat start 
address (RSA) and repeat end address (REA) registers. 


Key: 

Src — General addressing modes Dreg -— Register mode (any register) 
Src1 -— Three-operand addressing modes Rn ~ Register mode (RO-R7) 

Src2 - Three-operand addressing modes Daddr — Destination memory address 
Csre — Conditional branch addressing modes ARn-~ —| Auxiliary register n (ARO-AR7) 
Sreg — Register mode (any register) Addr - 24-bit immediate address (label) 


Count — Shift value (general addressing modes) Cond -— Condition code (see Table 6-2, pg. 6-4) 
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Signal, Interlocked 
Operation: Signal interlocked operation 
Wait for interlock acknowledge 
Clear interlock 
An interlocked operation is signaled over XFO and XF1. After the inter- 
locked operation is acknowledged, it ends. 
STF An,Daddr Store Floating-Point Value 
Operation: Rn — Daddr 
Store the contents of an extended-precision register into a word in memory. 
The value that is stored is a floating-point number. 
STFI An,Dadadr Store Floating-Point Value, Interlocked 
Operation: Rn — Daddr 
Signal end of interlocked operation 
The contents of the source operand are stored at the destination. An in- 
terlocked operation is signaled over XFO and XF1. The operands are 
floating-point values. 


STI Sreg,Daddr Store Integer 
Operation: Sreg ~ Daddr 


Store the contents of the source register into a word in memory. The value 
that is stored is an integer. 


STH Sreg,Daddr Store Integer, Interlocked 


Operation: Sreg —~ Daddr 


Signal end of interlocked operation 


The contents of the source operand are stored at the destination. An in- 
terlocked operation is signaled over XFO and XF1. The operands are signed 
integers. : 


SUBB Src,Dreg Subtract Integers with Borrow 
Operation: Dreg - Src - C > Dreg 


Load the difference between the destination register, the source operand, 
and the carry bit into the destination register. The operands are signed in- 
tegers. 


SUBB3 Src2,Src1,Dreg 
[SUBB Src2,Src7,Dreg] 


Subtract Integers with Borrow (3-Operand) 


Operation: Srci - Src2 - C > Dreg 


Load the difference between the source operands and the carry bit into the 
destination register. The operands are signed integers. 


SUBC Src,Dreg Subtract Integers Conditionally 


Operation: If Dreg - Src > 0 
[(Dreg-Src) << 1] OR 1 ~Dreg 
Else 
Dreg <<1 — Dreg 


if the difference between the destination and the source operands is greater 


than or equal to 0, then shift the difference left 1 bit, set the LSB to 1, and 
store the result in the destination register. 


if the difference between the destination and the source is less than zero, 
left shift the contents of the destination register by 1 bit. 


SUBC is equivalent to a single step of an integer divide. The operands are 
unsigned integers. 
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SUBF Src,Rn Subtract Floating-Point Values 


Operation: Rn - Src > Rn 


Subtract the source operand from the contents of the extended-precision 
register and store the result in the register. Both operands are floating- 
point numbers. 


SUBF3 Src2,Src7,Rn 
[SUBF Src2,Src7,Rn] 


Subtract Floating-Point Values (3-Operand) 
Operation: Src - Src2 > Rn 


Subtract source 2 from source 1 and store the result in the extended- 
precision register. All the operands are floating-point numbers. 


SUBI Src,Dreg Subtract Integers 


Operation: Dreg - Src > Dreg 


Subtract the source operand from the contents of the destination register 
and store the result in the destination register. Both operands are signed 
integers. 


SUBI3 Srce2,Src7,Dreg 
[SUBI Srce2,Srce7,Dreg] 


Subtract Integers (3-Operand) 
Operation: Srci - Src2 > Dreg 


Subtract source 2 from source 1 and store the result in the destination re- 
gister. All the operands are signed integers. 


SUBRB Src,Dreg Subtract Reverse Integer with Borrow 
Operation: Src - Dreg - C > Dreg 


Load the difference between the source, destination, and carry bit into the 
destination register. Both operands are signed integers. 


| SUBRF Src,Rn Subtract Reverse Floating-Point Value 


Operation: Src - Rn ~ Rn 


Subtract the contents of the extended-precision register from the source 
operand and store the result into the register. Both operands are float- 
ing-point numbers. 


SUBRI Src,Dreg Subtract Reverse Integer 
Operation: Src - Dreg > Dreg 


Subtract the contents of the destination register from the source operand 
and store the result into the destination register. Both operands are signed 
integers. 


Software Interrupt 
Operation: Perform emulator interrupt sequence. 


Note: Optional syntaxes are shown in [brackets]. 


Key: 

Src ~ General addressing modes Dreg — Register mode (any register) 
Src1  -—Three-operand addressing modes Rn —- Register mode (RO-R7) 

Src2 -— Three-operand addressing modes Daddr — Destination memory address 
Csrc -— Conditional branch addressing modes ARn_~ -—| Auxiliary register n (ARO-AR7) 
Sreg — Register mode (any register) Addr -— 24-bit immediate address (label) 


Count — Shift value (general addressing modes) Cond -— Condition code (see Table 6-2, pg. 6-4) 
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[syntax —SidSC~=“‘“*S*S*~*~*~*~«éi eseription —SCSC—C—~—SCS 


TRAPcond N | Trap Conditionally or Unconditionally 


[TRAP AN] Operation: 0 — ST(GIE) 
If cond= true 
next PC > *++SP 
trap vector N ~ PC 
Else 
Set ST(GIE) to original state 
continue 


lf the condition is true or missing, the PC contents are pushed on the sys- 
tem stack, the PC is loaded with the contents of the specified trap vector 
(V), and interrupts are disabled. Nis an immediate value from 0-31. 


TSTB Src,Dreg Test Bit Fields 
Operation: Dreg AND Src 


Perform a bitwise logical AND of the source and destination and set the 
appropriate flags on the result. This is a nondestructive compare; the re- 
sults of the compare are not stored. The source operand is an unsigned 
integer. 


TSTB3 Srce7,Sre2 Test Bit Fields (3-Operand) 
[TSTB Src7,Sre2}] Operation: Srct1 AND Src2 


Perform a bitwise logical AND of the two source operands and set the ap- 
propriate flags on the result. This is a nondestructive compare; the results 
of the compare are not stored. The source operands are unsigned integers. | 


XOR Src,Dreg Bitwise Exclusive OR 
Operation: Dreg XOR Src ~ Dreg 


| Perform a bitwise exclusive OR of the source and destination operands and 
store the result in the destination register. The source operand is an un- 
| signed integer. 


XOR3 Sre2,Sre1,Dreg Bitwise Exclusive OR (3-Operand) 
| [XOR Src2,Src7,Dreg] Operation: Srci XOR Src2 — Dreg 
Perform a bitwise exclusive OR of the two source operands and store the | 


result in the destination register. The source operands are unsigned inte- 
gers. | 


Note: Optional syntaxes are shown in [brackets]. 


Key: 

Src ~ General addressing modes Dreg -— Register mode (any register) 
Src1  - Three-operand addressing modes Rn — Register mode (RO-R7) 

Src2 — Three-operand addressing modes Daddr — Destination memory address 
Csre ~ Conditional branch addressing modes ARn~ —- Auxiliary register n (ARO-AR7) 
Sreg -— Register mode (any register) Val — Immediate value 


Count — Shift value (general addressing modes) Cond — Condition code (see Table 6-2, pg. 6-4) 
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6.2 Three-Operand Instructions 


Most instructions have only two operands; however, several arithmetic and 
logical instructions have three-operand versions. Three-operand instructions 
allow the TMS320C30 to read two operands from memory or the register file 
In a single cycle. 


6 Two-operand instructions have a single source operand (or shift count) 
and a destination operand. 


@ Three-operand instructions may have two source operands (or one 
source Operand and a count operand) and a destination operand. A 
source operand may be a memory word or a register. The destination 
of a three-operand instruction is always a register. 


Table 6-3 lists the instructions that have three-operand versions. 


Table 6-3. Summary Three-Operand Instructions 


ADDC3 Add with carry ADDF3 Add floating-point values 
ADDI3 Add integers AND3 Bitwise logical AND 


ANDN3 Bitwise logical AND with ASH3 Arithmetic shift 
complement 


Test bit fields 
Bitwise exclusive-OR 


CMPF3 Compare floating-point values CMPI3 


Note: 


You can omit the 3 for all three-operand instructions. 
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6.3 Parallel Instructions 


Some of the TMS320C30 instructions can occur in pairs that will be executed 
in parallel. Table 6-4 lists the valid instruction pairs. These parallel in- 
structions allow: 


@ Parallel loading of register, 
© Parallel arithmetic operations, and 


e Arithmetic or logical instructions that can be used in parallel with a store 
instruction. 


Each instruction in a pair is entered as a separate source statement; the second 
instruction must be preceded by two vertical bars (||). This example shows 
the syntax for parallel instructions: 


label: ADDI3 RO,*ARO,R1 ; Part 1 (label is optional) 
| | STI R4,*+AR11. ; Part 2 


Note that the first instruction in the pair may have a label, but the second in- 
struction cannot have a label. 


The assembler allows several relaxed syntax forms for parallel instructions: 


@ The vertical bars can be placed in column 1 or anywhere between col- 
umn 1 and the mnemonic. Here is another example of valid syntax for 
parallel instructions: 


label: MPYI3 RO,*AR1,RO 
|| ADDI3 *AR2,R1,R2 


@ The instructions in a parallel instruction pair may be specified in either 
order. For instance, the preceding example could also be specified as: 


label: ADDI3 *AR2,R1,R2 
|| MPYI3 RO,*AR1,RO 


@ If one of the instructions in a pair uses a three-operand instruction, you 
can omit the 2 for that instruction. 

MPYI3 RO,*AR1,RO canbe MPYI RO, *AR1,RO 

|| ADDI3 *AR2,R1,R2 written as || ADDI *AR2,R1,R2 


@ All commutative operations can be written in either order. For example, 


ADDI *ARO,R1,R2 can be written as ADDI R1,*ARO,R2 


® The third operand of a three-operand instruction specifies a destination 
register. You can omit the third operand if it is the same as the second 
operand. This allows you to use three-operand instructions that look like 
two-operand instructions. For example, 


ADDI3 *ARO,R2,R2 can be ADDI *ARO,R2 
MPYI3 *AR1,RO,RO written as MPYI *AR1,RO 

@ Instructions that can use the preceding two syntaxes include: 
ADDC3 AND3 LSH3 OR3 SUBI3 
ADDF3 ANDN3 MPYF3 SUBB3 XOR3 
ADDI3 ASH3 MPYI3 
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Note that all registers are read at the beginning of the execution cycle and 
loaded at the end of the execution cycle. If an instruction in a pair reads a 
register and another instruction writes to the same register, then the former 
instruction uses the contents of the register before it is modified by the /atter 
instruction. 


Table 6-4. Summary of Parallel Instructions 


Parallel Arithmetic with Store Instructions 


ABSF — Src2,Dst1 \Src2| > Dst1 

\| STF Src3,Dst2 \| Srce3 > Dst2 
ABS! Src2,Dst1 \Src2| > Dstt 

| STI Sre3,Dst2 \| Srce3 7 Dst2 
ADDF3 Src1,Src2,Dst1 Src1 + Src2 — Dstt 


|| STF Src3,Dst2 || Srce3 —~ Dst2 


| 
ADDI3 Src1,Src2,Dst1 Sre1 + Src2 —> Dstt 
|| STI Src3,Dst2 || Src3 > Dst2 


AND3 = Src2,Src1,Dst1 Src1 AND Src2 — Dst1 
1! STI Src3, Dst2 [| Sre3 — Dst2 


ASH3 = Count,Src2,Dst1 lf Count > 0 
i| STi Srce3, Dst2 Src2 << Count > Dst1 
|| Sre3 > Dst2 
Else 


Src2 >> |Count] > Dstt 
Src3 —~ Dst2 


lI 


FIX Src2,Dst1 Fix(Src2) — Dst1 
{| STI Src3, Dst2 || Sre3 > Dst2 
FLOAT Src2,Dst1 Float(Src2) — Dst1 
STF Src3,Dst2 || Sre3 —~ Dst2 
LDF Src2,Dst1 Src2 — Dst1 
STF Src3, Dst2 || Sre3 > Dst2 
LDI Srce2,Dst1 Src2 — Dst1 
\| STi Src3,Dst2 l| Src3 > Dst2 


LSH3 Count,Src2,Dst1 
{| STI Src3, Dst2 


lf Count > 0 
Src2 << Count > Dst1 
\| Src3 — Dst2 
Else 


Srce2 >> |Count| > Dstt 


= || Src3 —~ Dst2 
MPYF3 Src2,Src1,Dst1 Src1 x Src2 — Dst1 
\| STF Srce3, Dst2 || Src3 > Dst2 

Key: 

Src1 — Register mode (RO-R7) Srce2 — Indirect mode (disp. = 0, 1, IRO, IR1) 
Src3 — Register mode (RO-R7) Sr42 — Indirect mode (disp. = 0, 1, IRO, 1R1) 
Dst1 — Register mode (RO-R7) Dst2 — Indirect mode (disp. = 0, 1, IRO, IR1) 
Op3 — Register mode (RO or R1) Op6 - Register mode (R2 or R3) 


Op1,0p2,0p4.0p5 — Two of these operands must be specified using register mode and 
two must be specified using indirect mode 
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Table 6-4. Summary of Parallel Instructions (Concluded) 


Parallel Arithmetic with Store Instructions (continued) 


MPYI3 Src2,Src2,Dsti Src1 x Src2 — Dst1 
|| ST! Src3,Dst2 || Sre3 > Dst2 


NEGF  Src2,Dst1 0 - Src2 > Dstt | 
l| STF Src3,Dst2 || Src3 — Dst2 

NEGI Src2,Dst1 0 - Src2 > Dst1 
i| ST! Src3,Dst21 || Src3 > Dst2 


NOT Src2, Dst1 Src2 — Dst1 
i| STI Src3,Dst2 [| Src3 > Dst2 
ORS Src2,Src1,Dst1 


| Src1 OR Src2 > Dst1 
\| STi Src3,Dst2 l| Src3 > Dst2 | | | 
STF Src1,Dst1 | Src1 > Dst1 | 
\|. STF Src3, Dst2 | I| Src3 > Dst2 


STi Src1,Dst1 Src1 — Dst1 
|| STi Src3,Dst2 || Sre3 > Dst2 
SUBF3  Src2,Src1,Dst1 Srci1 - Src2 —> Dst1 
l| STF Src3, Dst2 || Sre3 — Dst2 
SUBI3  Src2,Src1,Dst1 Srei - Src2 —> Dstt 
| {| STi Src3,Dst2___ ||_ Src3 > Dst2 
XOR3_— Src2,Src1,Dst1 Srci1 XOR Src2 — Dstt 
| STi Src3, Dst2 || Src3 > Dst2_ 
_ Parallel Load Instructions 
[Syntax CdS peration Cd 
LDF Src2,Dst1 Src2 ~ Dst1 
|| LDF Src4,Dst2 || Sre4 — Dst2 
LDI Src2,Dst1 Src2 > Dst1 | 
|| LDI Src4,Dst2 | Src4 — Dst2 | 
Parallel Multiply and Add/Subtract (nstructions 
MIPYF3 Op1,0p2,0p3 Op1 x Op2 ~ Op3 
| ADDF3 Op4,0p5,O0p6 || Op4 + Op5 > Opé6 


MPYF3 Op1,0p2,0p3 Op1 x Op2 > Op3 | 
| || SUBF3 Op4,0p5,Op6 || Op4 - Op5 > Opé E 
MPYI3 Op1,0p2,O0p3 Op1 x Op2 > Op3 
|| ADDI3 Op4,0p5,Op6 | || Op4 + Op5 > Opé | 
MPYI3 Op1,0p2,0p3 ; Op1 x Op2 > Op3 
l] SUBI3 Op4,0p5,0p6 {| Op4 - Op5 > Op6 
Key: 


Src1 — Register mode (RO-R7) Src2 — Indirect mode (disp. = 0, 1, [RO, 1R1) 
Src3 — Register mode (RO-R7) Sr42 — Indirect mode (disp. = 0, 1, IRO, 1R1) 
Dst1 — Register mode (RO-R7) Dst2 — Indirect mode (disp. = 0, 1, IRO, R71) 
Op3 — Register mode (RO or R1) Op6 —- Register mode (R2 or R3) 


Op1,0p2,0p4,O0p5 — Two of these operands must be specified using register mode and 
two must be specified using indirect mode 
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6.4 Load and Store Instructions 


The TMS320C30 supports 12 load and store instructions, which are summa- 
rized in Table 6-5. These instructions: 


® Load a word from memory into a register, 
@ Store a word from a register into memory, or 
@ Manipulate data on the system stack. 


The TMS320C30 also provides you with the ability to load data conditionally; 
this is useful for locating the maximum or minimum value in a data set. 


Table 6-5. Summary of Load and Store Instructions 


| Load floating-point exponent | POP | Pop integer from stack 


ee Load floating-point value POPF Pop floating-point value from 
stack 


LDFeond Load floating-point value PUSH Push integer on stack 
conditionally 
stack 


LDicond Load integer conditionally Store floating-point value 
Load floating-point mantissa Store integer 
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6.5 Arithmetic instructions 


The TMS320C30 supports a complete set of arithmetic instructions. These 
instructions provide integer operations, floating-point operations, and multi- 
precision arithmetic. Table 6-6 summarizes these instructions. 


Table 6-6. Summary of Arithmetic Instructions 


ABSF Absolute value of a floating- NEGB Negate integer with borrow 
point number 


ABSI Absolute value of an integer | NEGF Negate floating-point value 


| Add integers with carry NEGI 
ADDF T} Add floating-point values | NORM | Normalize floating-point value 
: | RND 


ASH t| Arithmeticshift | ~—SSUBB__‘t| Subtract integers with borrow _| 
t | Compare floating-point values__| = SUBC___| Subtract integers conditionally 
CMPI___t| Compare integers | = SUBF_ | Subtract floating-point values __ 


FIX Convert floating-point value to SUBRB Subtract reverse-integer with 
integer borrow 
| FLOAT Convert integer to floating-point SUBRF Subtract reverse floating-point 
value » value 


T} Multiply floating-point values SUBRI 


t Two and three operand versions 


6.6 Logical Instructions 


The TMS320C30 supports a complete set of logical instructions, which are 
summarized in Table 6-7. 


Table 6-7. Summary of Logical Instructions 


Description 


Tt Two and three operand versions 
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6.7 Program-Control Instructions 


These instructions control program flow by providing repeat modes (zero- 
overhead looping) and branching. The repeat modes support repetition of a 
block of code or of a single line of code. Both standard and delayed branching 
are supported. Table 6-8 lists the program-control instructions. 


Table 6-8. Summary of Program-Control Instructions 
Instruction Instruction Description 


Bcond[D] Branch conditionally (standard No operation 
or delayed) 


BR[D] Branch unconditionally RETI cond Return from interrupt 
standard or delayed) conditionally 
CALL Call subroutine RETS cond 
conditionally 


Return from subroutine 
CALLcond Call subroutine conditionally RPTB Repeat block of instructions 


| DBcond[D] Decrement and branch RPTS Repeat single instruction 
conditionally 
IDLE Idle until interrupt TRAP cond | Trap conditionally 


SWI Software interrupt 


6.8 Interlocked-Operation Instructions 


The interlocked-operations instructions support multiprocessor communi- 
cation. Table 6-9 lists the interlocked-operation instructions. 


Table 6-9. Summary of Interlocked-Operation Instructions 
| Instruction | Description —|_Instruction | Description 


| LDFI Load floating-point value, STFI Store floating-point value, 
interlocked interlocked 


LDII Load integer, interlocked STII | Store integer, interlocked 
SIGI Signal, interlocked 


6-23 


Instruction Set - LDP Instruction 


6.9 The LDP Instruction 
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The LDP (load data page) instruction is a special form of the LDI (load inte- 
ger) instruction. LDP allows you to load a register (usually the DP register) 
with the page number of a relocatable address. A page number is represented 
by the eight MSBs of a 24-bit address. The page number is combined with 
the 16 LSBs of an instruction word to form a direct address. 


The syntax for the LDP instruction is: 
[/abel] LDP expression|[,register] 


LDP assembles as an LDI instruction with an immediate source operand. 


© The expression is a relocatable address, which ts usually represented by 
a symbol name. 


e The 8 MSBs of the address are loaded into the destination register. lf 
you do not specify a reg/ster, the assembler will use the DP register as a 
default. 


At link time, expression may be relocated to a different page than it occupied 
at assembly time. The assembler generates a special relocation type that al- 
lows the linker to patch the correct page number into the LDP instruction. 


The following example illustrates use of the LDP instruction. Assume a vari- 
able named sym is defined in the .bss section as shown: 


-bss sym,l ; Allocate sym in .bss 


To read the value of sym using direct addressing, you must first load the DP 
register with the 8-bit pointer to the page on which sym is located. Normally, 
you do not know at assembly time where the .bss section will be loaded, so 
you must use an LDP instruction to load DP before accessing the variable: 


LDP sym ; Load DP with page number of sym 
LDI @sym, RO ; Use direct addressing to access sym 


Note that the register operand was omitted from the LDP instruction; DP was 
used as the default. 


Section / 


Macro Language 


The assembler supports a macro language that allows you to create your own 
“commands.” This is especially useful when a program executes a particular 
task several times. The macro language allows you to: 


Define your own macros 

Redefine existing opcodes and macros 

Access macro libraries created with the archiver 
Manipulate strings within a macro 

Define conditional and repeatable blocks within a macro 
Control macro expansion listing 


There are three phases of macro use: 


@ Macro definition. Macros must be defined before they can be in- 
voked. There are two methods for defining macros: 


1) Macros can be defined in the source file where they are used (or 
in a separate text file that is included with a .copy or .include di- 
rective). Because macros must be defined before they are called, 
it is a good practice to place all the definitions at the beginning of 
the file. 


2) .Macros can also be defined in a macro library. A macro library 
is a collection of files in archive format, created by the archiver. 
Each member of the archive file (macro library) may contain one 
macro definition that corresponds to the name of the member. You 
can access a macro library by using the .mlib directive. Because 
macros must be defined before they can be called, the .mlib direc- 
tive must appear in the source code before any of the macros in the 
library are called. 


@ Macro invocation. Once a macro has been defined, the macro name 
can be used as an opcode in a source program. This is referred to as a 
macro call. 

® Macro expansion. When the source program calls a macro, the as- 
sembler substitutes the statements within the macro definition for the 
macro call statement. 


This section discusses the following topics: 
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Macro Language - Macro Directives Summary 


7.1 Macro Directives Summary 


[Directive [—~S=S~<“C~“S*S™S~CS es eriptvon ~——SSCSCSC—“S*~*~S~S 


SMACRO 


SELSE 


| $LOOP 
SENDLOOP 
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Macro Definition Directive 
Syntax: macro name $MACRO /[parm7[, ..., parmp]] 


The SMACRO directive begins a macro definition. It must be the first statement in 
a macro definition. S$MACRO assigns a name to the macro and declares the macro 
parameters. 


macro name is the name of the macro. A macro name may be 1 to 32 alphanumeric 
characters; it must begin with a letter. Parms are optional parameters. When a 
macro is called, the assembler will associate the first operand in the macro call with 
the first parameter of the macro definition, and so on. 


Begin Conditional Block Directive 
Syntax:  $IF expression 


The SIF directive begins a conditional block. If the expression evaluates to a non- 
zero value, then the code following the SIF directive (up to an SELSE or SENDIF 
directive) will be assembled. 


Alternate Conditional Block Directive 
Syntax: SELSE 


The SELSE directive may be used within a conditional block. If the expression in 
an SIF directive evaluates to 0, then code following a corresponding $ELSE directive 
(up to an SENDIF directive) will be assembled. 


Terminate Conditional Block Directive 


Syntax: SENDIF 


The SENDIF directive terminates a conditional block. 


Terminate Macro Definition Directive 
Syntax: SENDM 


The SENDM directive terminates a macro definition. 
Begin Repeatable Block Directive 


Syntax: SLOOP expression 


The $LOOP directive begins a repeatable block. The expression is evaluated only 
once; the expression should evaluate to a value in the range 0-32767. 


Terminate Repeatable Block Directive 
Syntax: SENDLOOP 
The SENDLOOP directive terminates a repeatable block. 


Macro Language - Macro Libraries 


7.2 Macro Libraries 


A macro library is a collection of files that contain macro definitions. These 
files, or members, are bound into a single file (called an archive) by the ar- 
chiver. Each member of a macro library may contain one macro definition. 
The macro name and the member name must be the same, and the macro 
filename’s extension must be .asm. The files in a macro library must be unas- 
sembled source files. You can access the macro library by using the .mlib as- 
sembler directive: 


.mlib “macro library filename” 


When the assembler encounters an .mlib directive, it opens the library and 
creates a table of Its contents. The assembler enters the names of the indi- 
vidual members within the library into the opcode table as library entries; this 
redefines any existing opcodes or macros that have the same name. If one of 
these macros is called, the assembler extracts the entry from the library and 
loads it into the macro table. The assembler expands the library entry in the 
same manner as other macros, but it does not place the source code into the 
listing. Only macros that are actually called from the library are extracted, and 
they are extracted only once. 


You can create a macro library with the archiver by simply including the de- 
sired files in an archive. A macro library is no different from any other archive, 
except that the assembler expects the macro library to contain macro defi- 
nitions. 


The following example creates a macro library called maclib.1lib: 


ar30 -a maclib.lib macl.asm mac2.asm mac3.asm mac4.asm 


This example adds four macro files (macl.asm, mac2.asm, mac3.asm, and 
mac4.asm) to the library maclib.1lib. Note that this could be a new or an 
existing library; if the library already existed, this example would simply ap- 
pend the macros to the end of the library. 


Now you can specify maclib.1lib to the assembler with an .mlib directive, 
and call any of the macros that it contains: 


-mlib “maciib. Lib” 
macl >; Macro call 


The assembler assumes that the files in the archive contain macro definitions 
with the same names as the members. The assembler expects only macro 
definitions in a macro library; putting object code or miscellaneous source files 
into the library may produce undesirable effects. 
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Macro Language - Defining Macros 


7.3 Defining Macros 
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A macro definition is a series of source statements in the following format. 


macname SMACRO [parm] [,parmo]... [,parmp/] 


"7 


a“ 
model statements or macro directives 
" 


Ld 


a” 


SENDM 
where: 


macname names the macro. It must be placed in the source statement’s 
label field. Macro names are significant to 32 characters. The 
assembler places this name in the internal opcode table, replac- 
ing any instruction or previous macro definition with the same 
name. 


SMACRO _ identifies this source statement as the first line of a macro defi- 
nition; it must be placed in the opcode field. 


parms are optional parameters which may appear as operands for the 
S$MACRO directive. Parameters are not required by all macros. 


model statements 
are instructions or assembler directives that are used each time 
the macro is invoked. 


macro directives 
control the expansion of the macro or manipulate macro param- 
eters. 


SENDM terminates the macro definition. 


The contents of a single macro definition must be contained in the same file. 
Macro definitions cannot be nested, but other directives, instructions, and 
macro calls can be used in a macro definition. The assembler performs only 
limited error checking of macro definitions (during the definition phase), so 
multiple expansions of a macro may produce duplicate error messages. 


When a macro is called, the assembler substitutes the model statements and 
macro directives within the defirition for the macro call in the source code. 
Example 7-1 shows an example of a macro definition, how it is called, and 
how it is expanded in the source code. 


Macro Language - Defining Macros 


Example 7-1. Macro Definition, Call, and Expansion 


Macro Definition: The following code defines a macro, MOVREG, that has three 
parameters. 


OOoOoL1 REEKEKEKEKRERKRKEKRKRRERKEERRREKRERKERREKREKREREKREEREEKREKREKKEEKEKKREEE 


0002 MOVREG SMACRO pl1,p2,pN ; Begin macro definition 
0003 LDI rai Ol lat aes ; Model statement 

0004 LD 2p22,.3pN¢ ; Model statement 

0005 SLOOP 2 ; Begin repeat block 
0006 NOP ; Model statement 

0007 SENDLOOP ; End repeat block 

0008 SENDM ; End macro definition 


Macro Call: The MOVREG macro ts invoked in the source code. 


0009 KREKREEKREKRKEEKRRKKERKEKEKRKKRKERRIEKREKR KKK KBRERKKRREKREREKEKERKEREKREESE 
0010 MOVREG RO,R1,R2 ; Macro call 


Macro Expansion: The assembler substitutes the functional lines of the macro de- 
finition for the macro call. The macro parameters are replaced with the operands sup- 
plied in the macro call. 


10001 000000 08010000 LDI RO,R1 
£0002 000001 08020001 LDI R1,R2 
£0003 000002 OC800000 NOP 
£0004 000003 OC800000 NOP 


When the assembler encounters a macro definition, it places the macro name 
in the opcode table. This redefines any previously defined macro, library entry, 
directive, or instruction mnemonic that has the same name as the encountered 
macro. This allows you to expand the functions of directives and instructions, 
as well as to add new instructions. 


Caution: 


When you specify a macro library with the .mlib directive, the 
assembler places all the entries in the specified library into the 


opcode table - not just the macros that are called. Make sure 
that the macros and instructions you want to use are not rede- 
fined by macros in a macro library. 
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Macro Language - Macro Parameters 


7.4 Macro Parameters 


Macros can declare local parameters whose scope is limited to the defining 
macro. These parameters do not conflict with symbols defined outside the 
macro. Only the first eight characters of a parameter name are significant. A 
single macro can declare a maximum of 128 parameters. 


The assembler assigns initial values to macro parameters when the macro is 
called. For example, consider the following macro definition line: 


ADDUP S$MACRO  vali,val2,sum 


This example defines three parameters (vall1, val2, and sum). The assembler 
assigns values to these parameters when it expands the macro; each parameter 
corresponds to an operand in the macro call. 


The value that is assigned to a macro parameter is called a string value. The 
assembler will substitute a parameter’s string value into a model statement 
when you enclose the parameter name in colons. Parameters can be used this 
way anywhere in a model statement (as a label, an operand, etc.). 


Example 7-2 shows a macro that has four parameters. 


Example 7-2. Using Parameter Values 


packword SMACRO bij b2;b37 54 
* Make sure these are all in one word 
-even 
-field : 7,8 
-field : :,8 
-field : 7,8 
-field : :,8 
SENDM 


00000003 .set 
00000010 .set 
00000009 .set 
00000044 _set 


000000 00000037 .field 


packword 
000001 -even 
000001 00000003 .field 
000001 00001003 -field 
OO0001 00091003 shield 
000001 44091003 -field 


The packword macro packs four values into the four bytes of a word. The 
parameters b1, b2, b3, and b4 are assigned values corresponding to the values 
that are passed when the macro is called. 
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Macro Language - Conditional Blocks 


7.5 Conditional Blocks 


The SIF, SELSE, and SENDIF directives are used to construct conditional 
blocks within macro definitions. Conditional blocks can be nested up to ten 
levels deep. Blocks at all nesting levels must always be terminated with an 
SENDIF. The general format of a conditional block is: 


SIF well-defined expression 

code to assemble if expression is true (# 0) 
SELSE 

code'to assemble if expression is false (=0) 
SENDIF 


if the expression in the SIF statement evaluates to a nonzero value (true), then 
the code that follows it (up to an SELSE or SENDIF) will be assembled. If the 
expression evaluates to O (fa/se), then the assembler does not assemble the 
code that follows the SIF statement; if an SELSE directive is present, the as- 
sembler assembles the code that follows it (up to the SENDIF). 


All directives (SIF, SELSE, and SENDIF) in a single conditional block must 
appear in the same source module; the SENDIF cannot appear in an included 
file. A conditional block not terminated by the end of a source file (or upon 
encountering an SENDM directive) will produce an error. 


Conditional assembly directives that appear in a macro definition are evaluated 
each time the macro is expanded, not as it is defined. Unassembled code 
(code following a false $IF or an unused SELSE) is not scanned; no 
copy/include files are opened and no macros are defined in such blocks. 


Figure 7-1 shows an example of a macro with a conditional block. 


SMACRO pl,p2 

SIF :pls <> 3p2: 
-string “not equal” 
SELSE 

.string “equal" 
SENDIF 

SENDM 


OO000001 syml .set Bi 
O0000002 sym2 -set 2 


000000 CMPR syml, sym2 
000000 20746F6E -string "not equal" 
000001 61757165 
000002 Q000006C 


Figure 7-1. An Example of a Conditional Block 
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Macro Language - Repeatable Blocks 


7.6 Repeatable Blocks 


Repeatable blocks allow a section of code (or a section of a macro definition) 
to be repeatedly expanded. This is particularly useful for table generation. The 
format of a repeatable block is: 


SLOOP ~ well-defined expressions 
model statements or macro directives 


SENDLOOP 


The assembler evaluates the expression once when it enters the loop, and then 
it repeats the block expression number of times. The expression may be any 
legal expression or macro expression. 


The restrictions that apply to conditional blocks also apply to repeatable 
blocks. You can nest up to 10 blocks; you can nest conditional blocks within 
repeatable blocks, and repeatable blocks within conditional blocks. The as- 
sembler checks to see if blocks are nested properly; if they are not, the as- 
sembler produces an error message. The following example shows improper 
nesting: 


SLOOP expression 1 
SIF expression 2 
SENDLOOP 

SENDIF 


Note that the two blocks overlap rather than nest properly. This is an error, 
and the macro definition will be ignored. 


Example 7-3 shows an example of a repeatable block. 


Example 7-3. A Repeatable Block 
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SMACRO 
SLOOP 
-word 
SENDLOOP 
SENDM 


ve fa OAABBCCDDh 
000000 AABBCCDD -word OAABBCCDDh 
000001 AABBCCDD -word OAABBCCDDh 
000002 AABBCCDD -word OAABBCCDDh 


00001D AABBCCDD .word OAABBCCDDh 
QO001E AABBCCDD “word OAABBCCDDh 
OO001F AABBCCDD “word OAABBCCDDh 


Macro Language - Unique Labels 


7.7: Unique Labels 


Labels must be unique. If you use an ordinary label in a macro, and the macro 
is expanded more than once, the label in the macro defines the label/symbol 
more than once - this is illegal. The macro language supports a special form 
of label that allows you to create unique labels within macros. To form a 
unique label, simply follow the label name with a question mark; the syntax 
for a unique label is: 


label? 


Symbols that are defined in this manner can be used like any other symbol: 
you can declare them as global symbols, you can use them in expressions, etc. 
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Macro Language 


Section 8 


Archiver Description 


The TMS320C30 archiver lets you combine several individual files into a sin- 
gle file called an archive or a library. Each file within the archive is called a 
member. Once you have created an archive file, you can use the archiver to 
add more files to it, delete or replace existing members, or extract members. 


You can build libraries out of any type of files. Both the assembler and the 
linker accept archive libraries as input; the assembler can use libraries that 
contain individual source files, and the linker can use libraries that contain in- 
dividual object files. 


One of the most useful applications of the archiver is to build a library of ob- 
ject modules. For example, you could write several arithmetic routines, as- 
semble them, and then use the archiver to collect the object files into a single, 
logical group. You can then specify the object library as linker input. The 
linker will search through the library and include any members that resolve 
external references. 


You can also use the archiver to build macro libraries. You can create several 
separate source files, each of which contains a single macro, and then use the 
archiver to collect these macros into a single, functional group. The .mlib as- 
sembler directive lets you specify the name of a macro library to the assembler; 
during the assembly process, the assembler will search the specified library for 
the macros that you call. Section 7 discusses macros and macro libraries in 
detail. | 


This section contains the following topics: 
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Archiver Description - Development Fiow 


8.1 Archiver Development Flow 


Figure 8-1 shows the archiver’s role in the assembly language development 
process. Both the assembler and the linker accept libraries as input. 
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Figure 8-1. Archiver Development Flow 
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Archiver Description — Invoking the Archiver 


8.2 Invoking the Archiver 


To invoke the archiver, enter: 


ar30 /-/command[option] libname [filename; ... filename,/ | 


ar30 is the command that invokes the archiver; /ibname names an archive li- 
brary. If you don’t specify an extension for /bname, the archiver uses the de- 
fault extension .47b. The filenames name individual member files that are 
associated with the library. If you don’t specify an extension for a filename, 
the archiver uses the default extension .obj. 


The command tells the archiver how to manipulate the members in the library. 
A command can be preceded by an optional hyphen. You must use one of 
the following commands when you invoke the archiver, but you can only use 
one command per invocation. Valid archiver commands include: 


a adds the specified files to the library. Note that this command does not 
replace an existing member that has the same name as an added file; it 
simply appends new members to the end of the archive. It is possible for 
an archive to contain several members that have the same name. If you 
want to rep/ace existing members, use the r command. 


d deletes the specified members from the library. 


r replaces the specified members in the library. If you don’t specify any 
filenames, the archiver replaces the library members with files of the same 
name in the current directory. If the specified file is not found in the li- 
brary, the archiver adds It instead of replacing it. | 


t prints a table of contents of the library. If you specify filenames, only 
those files are listed. If you don’t specify any filenames, the archiver lists 
all the members in the specified library. 


x extracts the specified files. If you don’t specify any member names, the 
archiver extracts all the members in the library. When the archiver extracts 
a member, it simply copies the member into the current directory; it 
doesn't remove it from the library. 


In addition to one of the commands, you can specify the following options: 
e tells the archiver not to use the default extension .obj for member names. 
q (quiet) suppresses the banner and status messages. 


Sprints a list of the global symbols that are defined in the library. (This 
option is valid only with the -a, -r, and -d commands.) 


v (verbose) provides a file-by-file description of the creation of a new li- 
brary from an old library and tts constituent members. 


Note: 


It is possible (but not desirable) for a library to contain several members 
with the same name. If you attempt to delete, replace, or extract a mem- 


ber, and the library contains more than one member with the specified 
name, then the archiver deletes, replaces, or extracts the first member with 
that name. 
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8.3 Archiver Examples 


Here are some examples of using the archiver. 


® Example 1: 


This example. creates a library called function.1ib that contains the 
files sine.ohj, cos.obj, and f1t.obj. 


ar30 -a function sine cos flt 

TMS320C30 Archiver Version 1.10.01 

(c) Copyright 1987, 1988, Texas Instruments Inc. 
=> new archive ‘function.1lib' 

=> building archive 'function.1lib' 


fl 


Since these examples use the default extensions (.1ib for the library 
and .obj for the members), it is not necessary to specify them. 


@ Example 2: 


You can print a table of contents of function.1ib with the -t option: 


ar30 -t function 


TMS320C30 Archiver Version 5.xx 87.160 
(c) Copyright 1987, Texas Instruments Inc. 
FILE NAME SIZE DATE 
sine.obj 248 Mon Nov 19 01:25:44 1984 
cos.obj 248 Mon Nov 19 01:25:44 1984 
flt.obj 248 Mon Nov 19 01:25:44 1984 


e Example 3: 


You can explicitly specify extensions if you don’t want the archiver 
to use the default extensions; for example: 


ar30 -ave function.fn sine.asm cos .asm flt.asm 
TMS320C30 Archiver Version 1.10.01 
(c) Copyright 1987, 1988, Texas Instruments Inc. 
==> add 'sine.asm' 
==> add 'cos.asm' 
==> add 'flilt.asm' 
==> building archive 'function.fn' 


This creates a library called function.fn that contains the files 
sine.asm, cos.asm, and flt.asm. (-v is the verbose option.) 


@ Example 4: 


If you wanted to add some new members to a library, specify: 


ar30 -as function tan.obj arctan.obj area.obj 
TMS320C30 Archiver Version 1.10.01 
(c) Copyright 1987, 1988, Texas Instruments Inc. 
==> symbol defined: 'K2' 
==> symbol defined: 'Rossignol' 
==> building archive 'function.1lib' 


ar30 -a function tan.obj arctan.obj area.obj 
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Since this example doesn’t specify an extension for the libname, the ar- 
chiver adds the files to the library called function.lib. If func- 
tion.1lib didn’t exist, the archiver would create it. (The -s option tells 
the archiver to list the global symbols that are defined in the library.) 


®@ Example 5: 


lf you want to modify a member of a library, you can extract it, edit it, 
and replace it. In this example, assume there’s a library named mac- 
ros.lib that contains the members push.asm, pop.asm, and 
Swap.asm. 


ar30 -x macros push.asm 


The archiver makes a copy of push.asm and places it in the current di- 
rectory; it doesn’t remove push.asm from the library, though. Now you 
can edit the extracted file. To replace the copy of push. asm that’s in the 
library with the copy that was changed, enter: 


ar30 -r macros push.asm 
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Section 9 


Linker Description 


The TMS320C30 linker creates executable modules by combining COFF ob- 
ject files. The concept of COFF sections is basic to linker operation; Section 
3 discusses COFF sections in detail. 


As the linker combines object files, it performs the following tasks: 


e It allocates sections into the target system’s configured memory. 
@ It relocates symbols and sections to assign them to final addresses. 
@ It resolves undefined. external references between input files. 


The linker supports a C-like command language that controls memory con- 
figuration, output section definition, and address binding. The language 
supports expression assignment and evaluation, and provides two powerful 
directives, MEMORY and SECTIONS, that allow you to: 


@ Define a memory model that conforms to target system memory, 
® Combine object file se¢tions, 

@ Allocate sections into specific areas of memory, and 

@ Define or redefine global symbols at link time. 


Topics in this section include: 
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9.1 Linker Development Flow 


9-2 


Figure 9-1 illustrates the linker’s role in the assembly language development 
process. The linker accepts several types of files as input, including object 
files, command files, libraries, and partially linked files. The linker creates an 
executable COFF object module that can be downloaded to one of several 


development tools or executed by a TMS320C30. 
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Figure 9-1. Linker Development Flow 


Linker Description - Invoking the Linker 


9.2 Invoking the Linker 


The general syntax for invoking the linker is: 


| Ink30 /-options] filename; ... filename, 


Ink30 is the command that invokes the linker. The options (discussed in 
Section 9.3) can appear anywhere on the command line or in a linker com- 
mand file. The filenames can be object files, linker command files, or archive 
libraries. The default extension for all input files is .obj; any other extension 
must be explicitly specified. The linker can determine whether the input file is 
an object file or an ASCII file that contains linker commands. The default 
output filename is a.out. | 


There are three methods for invoking the linker: 


@ Specify options and filenames on the command line. This example links two 
files, filel.obj and file2.obj, and uses the -o option to create an output 
module named link.out. 


Ink30 filel.obj file2.obj -o link.out 


® Enter the Ink30 command with no filenames and no options; the linker will 
prompt for them: 


Command files : 
Object files [.obj] 
Output files [ ] : 
Options 


For command files, enter one or more command file names. 


For object files, enter one or more object file names. The default extension is 
obj. Separate the filenames with spaces or commas; if the last character is a 
comma, the linker will prompt for an additional line of object file names. 


The output file is the name of the linker output module. This overrides any -o 
options entered with any of the other prompts. If there are no -o options and 
you do not answer this prompt, the linker will create an object file with the 
default filename of a.out. 


The options prompt is for additional options, although you can also enter op- 
tions in a command file. Enter them with hyphens, just as you would on the 
command line. 


® Put filenames and options in a linker command file. For example, assume the 
file Linker .cmd contains the following lines: 


-o link.out 
filel.obj 
file2.obj 


Now you can invoke the linker from the command line; specify the command 
file name as an input file: 1nk30 linker.cmd 


When you use a command file, you can also specify other options and files on 


the command line. For example, you could enter: 
ink30 -m link.map linker.cmd file3.obj 


The linker reads and processes a command file as soon as it encounters it on 
the command line, so it links the files in this order: filel.obj, file2.obj, 
and file3.obj. This example creates an output file called link.out and a 
map file called Link.map. 
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9.3 Linker Options 


Linker options control linking operations. They can be placed on the com- 
mand line or in a command file. All linker options must be preceded by a hy- 
phen (-). The order in which options are specified is unimportant, except for 
the -| and -i options. Options are separated from arguments (if they have 
them) by an optional space. Table 9-1 summarizes the linker options. 


Table 9-1. Linker Options Summary 


Option Description 


Produce an absolute, executable module. This is the default: if neither -a nor 
-r is specified, the linker acts as if -a is specified. 


Produce a relocatable, executable object module. . 


Use linking conventions defined by the ROM autoinitialization model of the C 


compiler. i 


Use linking conventions defined by the RAM autoinitialization model of the C 
compiler. 
Defines a global symbol! that specifies the primary entry point for the output 
module. 

-f fill value Set the default fill value for holes within output sections; f/// value is a 4-byte | 
constant. 


Make all global symbols static. [ 


-1 dir Alter the library-search algorithm to look in dr before looking in the default lo- 
cation. This option must appear before the -! option. 


ame an archive library file as linker input; f//ename is an archive library name. 
Produce a map or listing of the input and output sections, including holes, and 


-l filenamet 
-m filenamet 


place the listing in filename. 


| -oO filename’ Name the executable output module. The default filename is a.out 
Request a quiet run (suppress the banner). 
Retain relocation entries in the output module. 


Strip symbol table information and Jine number entries from the output modules. 


-u symbol Place an unresolved external symbo/ into the output module’s symbol! table 


T The filename must follow operating system conventions. 


9.3.1 Relocation Capability (-a and -r Options) 


One of the tasks the linker performs is re/ocation. Relocation is the process 
of adjusting all the references to a symbol when the symbol’s address changes. 
The linker supports two options (-a and -r) that allow you to choose whether 
you will produce an absolute or a relocatable output module. 


@ Producing an Absolute Output Module (-a Option) 


When you use the -a option without the -r option, the linker produces 
an absolute, executable output module. Absolute files contain no relo- 
cation entries. Executable files: , 


== Contain specia! symbols defined by the linker (Section 9.11.4, 
page 9-32, describes these symbols), 

= Contain an optional header that describes information such as the 
program entry point, and 

= Contain no unresolved references. 


is 
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This example links filel.obj and file2.obj and creates an absolute 
output module called a.out: 


Ink30 -a filel.obj file2.obj 


Note: 


If you do not use the -a or the -r option, the linker acts as if you specified 
-a. 


@ Producing a Relocatable Output Module (-r Option) 


When you use the -r option without the -a option, the linker retains re- 
location entries in the output module. If the output module will be re- 
located (at load time) or relinked (by another linker execution), use -r 
to retain the relocation entries. 


The linker produces an unexecutab/e file when you use the -r option 
without -a. A file that is not executable does not contain special linker 
symbols or an optional header. The file may contain unresolved refer- 
ences, but these references do not prevent creation of an output module. 


This example links filel.obj and file2.obj and creates a relocatable 
output module called a. out: 


Ink30 -r filel.obj file2.obj 


The output file a. out can be relinked with other object files or relocated 
at load time. (Linking a file that will be relinked with other files is called 
partial linking. For more information, see Section 9.13, page 9-37.) 


@ Producing an Executab/e Relocatabie Output Module (-ar) 


lf you invoke the linker with both the -a and -r options, the linker pro- 
duces an executable, relocatable object module. The output file contains 
special linker symbols, contains an optional header, and all symbol ref- 
erences are resolved (this is normal for a relocatable file); however, the 
relocation information is retained. 


This example links £ilel.obj and file2.obj and creates an executa- 
ble, relocatable output module called xr.out: 


Ink30 -ar filel.obj file2.obj -o xr.out 


Note that you can string the options together (Ink30 -ar) or you can 
enter them separately (Ink30 -a -r). 


@ Relocating or Relinking an Absolute Output Module 


The linker issues a warning message (but continues executing) when it 
encounters a file that contains no relocation or symbol table information. 
Relinking an absolute file can only be successful tf each tnput file con- 
tains no information that needs to be relocated (that is, each file has no 
unresolved references and is bound to the same virtual address that it 
was bound to when the I!nker created it). 
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9.3.2 C Language Options (-c and -cr Options) 


The -c and -cr options cause the linker to use linking conventions that are 
required by the TMS320C30 C compiler. 


® The -c option tells the linker to use the ROM autoinitialization model. 
@ The -cr option tells the linker to use the RAM autoinitialization model. 


For more information about linking C code, see section Section 9.14 on page 
9-38. 


9.3.3 Define an Entry Point (-e global symbo/ Option) 


The memory address that a program begins executing from is called the entry 
point. When a loader loads a program into target memory, the program 
counter must be initialized to the entry point; the PC then points to the be- 
ginning of the program. 


The linker can assign one of four possible values to the entry point. These 
values are listed below in the order in which the linker tries to use them. If 
you use one of the first three values, it must be an external symbol in the 
symbol table. Possible entry point values include: 


1) The value specified by the -e option. The syntax is -e <global sym- 
bol> where global symbol defines the entry point and must appear as 
an eternal symbol in one of the input files to be linked. 


2) The value of symbol —c_int0OO (if present). —c_intOO must be the 
entry point if you are linking code produced by the C compiler. 


3) The value of symbol —main (if present). 
4) Zero (default value). 


This example links filel.obj and file2.obj and sets the entry point to the 
value of the symbol begin. This symbol must be defined as external in filel 
or file2. 


1nk30 -e begin filel.obj file2.obj 


9.3.4 Set Default Fill Value (-f ce Option) 
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The -f option fills the holes formed within output sections or initializes unini- 
tialized sections when they are combined with initialized sections. This allows 
you to initialize memory areas during link time without reassembling a source 
file. The argument cc is a 4-byte constant (up to eight hexadecimal digits). 
If you do not use -f, the linker uses O as the default fill value. 


This example fills holes with the hexadecimal value AABBCCDDh: 
1nk30 -f OAABBCCDDh filel.obj file2.obj 


Linker Description -— Linker Options 


9.3.5 Make All Global Symbols Static (-h Option) 


9.3.6 Alter 


The -h option makes all global symbols static. This “hides” symbols, because 
static symbols are not visible to externally linked modules. This allows ex- 
ternal symbols with the same name (in different files) to be treated as unique. 


The -h option effectively nullifies all .global assembler directives. All symbols 
become local to the module in which they were defined, so no external refer- 
ences are possible. _ 


For example, assume filel.obj and file2.obj both define global symbols 
called ext. By using the -h option, these files can be linked without conflict. 
The symbol ext defined in,filel.obj is treated separately from the symbol 
ext defined in file2.obj. 


Ink30 -h filel.obj file2.obj 


the Library Search Algorithm (-i dir & -1| filename/C—DIR) 


Usually when you want to specify a library input, you simply enter the library 
name as you would any other input filename; the linker looks for the library in 
the current directory. For example, suppose the current directory contains the 
library object.1ib. Assume that this library defines symbols that are refer- 
enced in the file filel.obj. This is how you link the files: 


ink30 filel.obj object.1lib 


If you want to use a library that is not in the current directory, use the -| 
(lowercase “L”) linker option. The syntax for this option is -l filename. The 
filename is the name of an archive library; the space between -| and the 
filename is optional. 


You can augment the linker’s directory search algorithm by using the -i linker 
option or the environment variable. The linker searches for object libraries in 
the following order: 


1) It searches directories named with the -i linker option. 

2) It searches directories named with the environment variable C—DIR. 

3) If C_DIR is not set, it searches directories named with the assembler’s 
environment variable, A—DIR. 

4) It searches the current directory. 
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9.3.6.1 -i Linker Option 


The -i option names an alternate directory that contains object libraries. The 
syntax for this option is -i dir. dir names a directory that contains object li- 
braries; the space between -i and the directory name is optional. When the 
linker is searching for object libraries named with the -! option, it searches 
through directories named with -i first. Each -i option specifies only one di- 
rectory, but you can use several -i options per invocation. When you use the 
-j option to name an alternate directory, it must precede the -! option on the 
command line or in a command file. 


As an example, assume that two archive libraries called r.1lib and lib2.1ib 
reside in directories called: 


® \ld and \1d2 (DOS) 
@ [1d] and [1d2} (VMS), or 
6 /1d and /1d2 (UNIX). 


You can use both libraries during a link: 

DOS: 1nk30 £fl.obj £2.obj -i\ld -i\ld2 -lr.lib -1lib2.1lib 
VMS: 1nk30 fl.obj £2.obj -if1d] -if[id2] -lr.lib -1lib2-.1lib 
UNIX: 1nk30 £1.0bj} £2.obj -i/ld -i/1d2 -lr.lib -11ib2.1lib 


9.3.6.2 Environment Variable (C—DIR) 
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An environment variable is a system symbol that you define and assign a string 
to. The linker uses an environment variable named C—DIR to name alternate 
directories that contain object libraries. The command for assigning the envi- 
ronment variable is: 


DOS: set C—DIR=pathname; another pathname ... 
VMS: assign C—DIR” pathname, another pathname... 


La 


UNIX: setenv C—DIR” pathname; another pathname ... 


The pathnames are directories that contain object libraries. Use the -! option 
on the command line or in a cammand file to tell the linker which libraries to 
search for. 


As an example, assume that two archive libraries called r.1ib and 1ib2.1ib 
reside in directories called: | 

@® \ldir and \ldir2 (DOS), 

S [ldir]j and [1ldir2] (VMS), or 

e /idir and /1d2 (UNIX). 

You can use both libraries during a link; set the environment variable first: 


DOS: set C_DIR=\ldir; \ldir2 
1nk30 f1.obj £2.obj -1 r.lib -1 1ib2.1ib 


Linker Description - Linker Options 


VMS: assign C_DIR "[ldir]; [ldir2]" 
‘ Ink30 fl.obj £2.obj -lr.lib -1 1ib2.1ib 


UNIX: setenv C_DIR "/ldir;/ldir2 
1nk30 fl.obj f2.obj} -l xv.lib -1 1ib2.1ib 


Note that the environment variable remains set until you reboot the system or 
reset the variable by entering: 


DOS: set C—DIR= 
VMS: deassign C_DIR 
UNIX: setenv C_DIR " " 


The assembler uses an environment variable named A—DIR to name alternate 
directories that contain copy/include files or macro libraries. If C—DIR is not 
set, the linker will search for object libraries in the directories named with 
A—DIR. 


Section 9.5 (page 9-13) contains more information about object libraries. 


9.3.7 Create a Map File (-m filename Option) 


The -m option creates a link map listing and puts it in filename. This map 
describes: 


e Memory configuration, 
@ Input and output section allocation, and 
e The addresses of external symbols after they have been relocated. 


The map file contains the name of the output module, the entry point, and 
may also contain up to three tables: 


® A table showing the new memory configuration, if any nondefault 
memory is specified. 


@ A table showing the linked addresses of each output section and the 
input sections that make up the output sections. 


@ A table showing each external symbol and its address. This table has 
two columns: the left column contains the symbols sorted by name and 
the right column contains the symbols sorted by address. 


This example links filel.obj and file2.ob j and creates a map file called 
map .out: 


ink30 filel.obj file2.obj -m map.out 


Section 9.15 (page 9-41) shows an example of a map file. 
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9.3.8 Name an Output Module (-o filename Option) 


The linker always creates an executable output module. If you do not specify 
a filename for the output module, the linker gives it the default name a.out. 
If you want to write the output module to have another name, use the -o op- 
tion. The filename is the new output module name. | 


This example links filel.obj and file2.obj and creates an output module 
named run.out: 


Ink30 -o run.out filel.obj file2.obj 


9.3.9 Specify a Quiet Run (-q Option) 


The -q option suppresses the linker’s banner when -q ts the first option on the 
command line or in a command file. This option ts useful for batch operation. 


9.3.10 Strip Symbolic Information (-s Option) 


9.3.11 


The -s option creates a smaller output module by omitting symbol table in- 
formation and line number entries. The -s option is useful for production ap- 
plications, when you must create the smallest possible output module. 


This example links filel.obj and file2.obj and places the output mod- 
ule, stripped of line numbers and symbol table information, named nol- 
ink.out: 


Ink30 -o nolink.out -s filel.obj file2.obj 


Note that using the -s option limits later use of a symbolic debugger, and may 
prevent a file from being relinked. 


Introduce an Unresolved Symbol (-u symbo/ Option) 


The -u option introduces an unresolved symbol into the linker’s symbol table. 
This forces the linker to search through a library and include the module that 
defines the symbol. Note that the linker must encounter the -u option before 
it links in the member that defines the symbol. 


For example, suppose a library named rts.1lib contains a member that de- 
fines the symbol symtab, none of the object files you are linking reference to 
symtab. However, suppose you plan to relink the output module, and you 
would like to include the library member that defines symtab in this link. 
Using the -u option as shown below forces the linker to search rts.1lib for 
the member that defines symtab and to link in the member. 


Ink30 -u symtab filel.obj file2.obj rts.1lib 


If you did not use -u, this member would not be included because there is no 
explicit reference to it in filel.obj or file2.obj. 


Linker Description - Command Files 


9.4 Linker Command Files 


Linker command files allow you to put linking information in a file; this is 
useful when you often invoke the linker with the same information. Linker 
command files are also useful because they allow you to use the MEMORY 
and SECTIONS directives to customize your application. You must use these 
directives in a command file; you cannot use them on command line. Com- 
mand files are ASCII files that contain one or more of the following: 


®@ Input filenames, which specify object files, archive libraries, or other 
command files. (If a command file calls another command file as input, 
this statement must be the /ast statement in the calling command file. 
The linker does not return from the called command files. ) 


® Linker options, which can be used in the command file in the same 
manner that they are used on the command line. 


@ The MEMORY and SECTIONS linker directives. The MEMORY directive 
allows you to specify the target memory configuration. The SECTIONS 
directive controls how sections are built and allocated. 


® Assignment statements, which define and assign values to global sym- 
bols. 


To invoke the linker with a command file, enter the Ink30 command and fol- 
low it with the name of the command file: 


Ink30 command file name 


The linker processes input files in the order that it encounters them. If the 
linker recognizes a file as an object file, it links the file. Otherwise, it assumes 
a file is a command file and begins reading and processing commands from 
it. 

Figure 9-2 shows a sample linker command file called link.cmd. (Figure 
9-12 on page 9-42 contains another example of a linker command file.) 


EEE EE EAE LE LAMAR RNR LN EERE A ASML RAE RRR SS CE 


bg Sample Linker Command File mf. 
JETER LEA ARE RARER A RAS RAR AA Ce AR AR ee RON N, 7 


a.obj First input filename 


lope! ong, Second input filename 
-O prog.out rs Option to specify output file 
-m prog.map Option to specify map file 


Figure 9-2. An example of a Linker Command File 


This sample file in Figure 9-2 contains only filenames and options. (Note that 
you can place comments tn a command file by delimiting them with /* and 
*/.) To invoke the linker with this command file, enter: 


ink30 lLink.cmd 


Linker Description - Command Files 


You can also place other parameters on the command line when you use a 
command file: 


inksO: =r. Jink.cmd.‘c.oOb] d.0b4 


The linker processes the command file as soon as it encounters it, SO a.obj 
and b.obj are linked into the output module before c.obj and d.obj. 


You can also specify multiple command files. If, for example, you have a file 
called names.1st that contains filenames and another file called dir.cmd 
that contains linker directives, you can enter: 


1lnk30 names.lst dir.cmd 


A command file can call another command file; this type of nesting Is limited 
to 16 levels. If a command file names another command file as input, this 
statement must be the /ast statement in the calling command file. 


Blanks and blank lines that appear in a command file are insignificant except 
as delimiters. This also applies to the format of linker directives in a command 
file. Figure 9-3 shows a sample command file that contains linker directives. 
(Linker directive formats are discussed tn later sections.) 


PRR ERA RRR te ee te te Re A BO NG Re Ree ee ee ey 


7" Sample Linker Command File with Directives * 
LREREEAE REAR EL AAS R ALAR ERAS EARS AAA AAR SION 


a.obj b.obj c.obj /* Input filenames my 
-O prog.out -m prog.map /* Options 7. 


MEMORY /* MEMORY directive i J 
{ 


RAM: o = 100h 0100h 
ROM: o = 01000h 100h 
} 


SECTIONS /* SECTIONS directive * / 
{ 


-text: 
-data: 
.bSS: 


} 


Figure 9-3. An Example of a Command File with Linker Directives 


The following names are reserved as key words for linker directives. Do not 
use them as symbol or section names in a command file. 


align | (lowercase "L”) origin 
ALIGN len ORIGIN 
block length page 
BLOCK LENGTH PAGE 
COPY MEMORY range 
DSECT NOLOAD SECTIONS 
group O spare 
GROUP org 


Linker Description - Object Libraries 


9.5 Object Libraries 


An object library is a partitioned archive file that contains complete object files 
as members. Usually, a group of related modules are grouped together into a 
library. When you specify an object library as linker input, the linker includes 
any members of the library that define existing unresolved symbol references. 
You can use the TMS320C30 archiver to build and maintain archive libraries; 
Section 8 contains more information about the archiver. 


Using object libraries can reduce linking time and can reduce the size of the 
executable module. If a normal object file that contains a function is specified 
at link time, it is linked whether It is used or not; however, if that same function 
is placed in an archive library, it is only included if it is referenced. 


The order in which libraries are specified is important because the linker in- 
cludes only those members that resolve symbols that are undefined when the 
library is searched. The same library can be specified as often as necessary; It 
is searched each time it is included. A library has a table that lists all external 
symbols defined in the library; the linker searches through the table until it 
determines that it cannot use the library to resolve any more references. 


The following example links several object files and libraries; assume that: 


@ Input files £1.obj and £2.obj both reference an external function 
named clrscr. 


Input file £1.ob j references the symbol origin. 

Input file £2.ob j references the symbol fillclr. 

Library Libc.1ib, member O, contains a definition of origin. 
Library liba.1ib, member 3, contains a definition of fillclr. 
Member 1 of both libraries defines clrscr. 


If you enter: 1nk30 f1.0obj liba.1lib f2.obj libc.lib 
then: 


e Member 1 of liba.1lib satisfies both references to clrscr, because 
the library is searched and clrscr is defined before £2.obj references 
it. 


8 Member 0 of libc.1ib satisfies the reference to origin. 
@ Member 3 of liba.1ib satisfies the reference to fillclr. 


If, however, you enter: 1nk30 fl.obj £2.o0bj libc.lib liba.lib 
then the references to clrscr are satisfied by member 1 of libc.1lib. 


If none of the linked files reference symbols defined in a library, you can use 
the -u option to force the linker to include a library member. The next example 
creates an undefined symbol rout1 tn the linker’s global symbol table: 


Ink30 -u routl libc.lib 


If any members of libc.1ib define routi, then the linker includes those 
members. Note that it is not possible to control the allocation of individual 
library members; members are allocated according to the SECTIONS directive 
default allocation algorithm. 


Section 9.3.6 (page 9-7) describes methods for specifying directories that 
contain object libraries. 


Linker Description - The MEMORY Directive 


9.6 The MEMORY Directive 


The linker determines where output sections should be allocated into memory; 
the linker must have a model of target memory to accomplish this task. The 
MEMORY directive allows you to specify a model of target memory, so you 
can define the types of memory your system contains and the address ranges 
they occupy. The linker maintains the model as it allocates output sections, 
and uses the model to determine which locations in the target system can be 
used for object code. 


The memory configurations of TMS320C30 systems differ from application to 
application. The MEMORY directive allows you to specify a variety of con- 
figurations to meet all applications. After you use the MEMORY directive to 
define a memory model, you can use the SECTIONS directive to allocate out- 
put sections into defined memory. 


9.6.1 Default Memory Model 


If you do not use the MEMORY directive, the linker uses a default memory 
model that is based on the TMS320C30 architecture. This model assumes that 
the full 24-bit address space (224 locations) is present in the system and 
available for use. 


9.6.2 MEMORY Directive Syntax 


The MEMORY directive identifies ranges of memory that are physically present 
in the target system and can be used by a program. Each memory range has 
a name, a starting address, and a length. 


When you use the MEMORY directive, be sure to identify all the memory 
ranges that are available to load object code into. Memory that is defined by 
the MEMORY directive is configured memory; any memory that you do not 
explicitly account for with the MEMORY directive is unconfigured 
memory. The linker does not place any part of a program into unconfigured 
memory. You can represent nonexistent memory spaces by simply not in- 
cluding an address range in a MEMORY directive statement. 


The MEMORY directive is specified in a command file by the word MEMORY 
(uppercase), followed by a list of memory range specifications enclosed in 
braces. The MEMORY directive in Figure 9-4 defines a system that has 4K 
of ROM at address 0 and 8K of RAM at address OEOQOOh. 


[BRR RRR KERR KKK REE KEKE KKK KEK KKK RRR KEKE KERR KEK ERK / 


/* Sample command file with MEMORY directive * 
REKERKRKEEKEREERERERRERERRRERERKRREKEKKRRERREEKREREKERERKRKKEKRKEKRER 


filel.obj file2.obj hal Input files * 


-O prog.out j* Options 
eae 
ROM =: origin 00000h length 1000h 


RAM : origin OEOO0O0h ; length 2000h 


Figure 9-4. An Example of the MEMORY Directive 


Linker Description - The MEMORY Directive 


Now you could use the SECTIONS directive to tell the linker where to link the 
sections. For example, you could allocate the .text and .data sections into the 
area named ROM and allocate the .bss section into the area named RAM. 


The general syntax of the MEMORY directive is: 


MEMORY 
name 7 [(attr)]: Origin = constant , length = constant 
name n [(attr)] : origin = constant , length = constant 
name names a memory range. A memory name may be 1 to 8 characters; 


attr 


origin 


length 


valid characters include A-Z, a-z, $, .. and —. The names have no 
significance to the program; they simply identify memory ranges for 
the linker. Memory range names are internal to the linker and are not 
retained in the output file or in the symbol table. 


specifies 1 to 4 optional attributes that are associated with the named 
range. Valid attributes include R (readable memory), W (writable 
memory), X (executable memory), and I (initializable memory); attri- 
butes must be enclosed in parentheses. If you do not specify any 
attributes for a memory range, then the range has a// four attributes. 
All memory in the default mode} has all four attributes. The following 
example defines a memory range that is readable and executable: 


MEMORY 
{ ROM (RX) : 0 = O, 1 = 01000h } 


specifies the starting address of a memory range. It may be entered 
as origin, org, or o. The value, specified in words, is a long integer 
constant, and may be decimal, octal, or hexadecimal. 


specifies the length of a memory range. It may be entered as /ength, 
len, or /. The value is specified in words as a long integer constant 
(decimal, octal, or hexadecimal). 


Figure 9-5 illustrates the memory map defined by Figure 9-4. 


Memory 


1000h 


OEOOOh 


} 10000h 


Linker Description - The SECTIONS Directive 


9.7 The SECTIONS Directive 


The SECTIONS directive tells the linker how to combine sections from input 
files into sections in the output module and where to place the output sections 
in memory. In summary, the SECTIONS directive: 


Y Describes how input sections are combined into output sections, 
@ Defines output sections in the executable program, 


e Specifies where output sections are placed in memory (in relation to 
each other and to the entire memory space), and 


@ Permits renaming of output sections. 


9.7.1 Default Sections Configuration 


lf you do not specify a SECTIONS directive, the linker uses a default algorithm 
for combining and allocating the sections. Section 9.9 (page 9-27) describes 
this algorithm in detail. 


9.7.2 SECTIONS Directive Syntax 


The SECTIONS directive is specified in a command file by the word SEC- 
TIONS (uppercase), followed by a list of output section specifications en- 
closed in braces. Figure 9-6 contains an example of the SECTIONS directive. 


EERSTE EE EERE ELE ERS eS OD SO Be RN ee ae 


/* Sample command file with SECTIONS directive */ 
REEKKKEKRRKRKRKRKKRRKRKKKRRKREKKEKKRKREKKERRKKKKERRR RRR RHEE 


£i.let.ob7 file2.obj /* Input files * 
=O Pprog.out | /* Options xf 
SECTIONS 
{ 

.text 01000h : { } 


-data : { £filel.obj(.data) } 


init 
/ 
/ filel.obj(init) 
/ file2.obj(.data) 


-bss ALIGN(16) : { } 


Figure 9-6. An Example of the SECTIONS Directive 


The general syntax of the SECTIONS directive is: 
SECTIONS 
{ 


section specification 7 
section specification 2 
section specification n 


} 
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Each section specification defines an output section. (An output section is a 
section in the output file.) The syntax for a section specification is: 


name [ binding or align(n) 7: 


input sections 
assignments 
} [ =fill value] [ > named memory ] 


name 


binding 


align(n) 


input 
sections 


assignment 


fill value 


> named 
memory 


names the section in the output file. Only the first 8 characters 
of output section names are significant. 


is optional and assigns the section to a specific physical ad- 
dress in target memory. Section 9.7.4 (page 9-20) discusses 
assigning an address to an output section. 


is optional and specifies that the section should be aligned on 
an address boundary (the actual address is determined by the 
linker). Section 9.7.4 (page 9-20) discusses aligning an out- 
put section. 


is a list of input sectio.is that are combined to form the output 
section. The list is enclosed in braces. Section 9.7.3 (page 
9-18) discusses specifying input sections in detail. 


is optional and defines the value of symbols at link time or 
creates uninitialized spaces (called holes) between input sec- 
tions within the output section. Section 9.11 (page 9-30) 
discusses linker assignment statements, and Section 9.12 
(page 9-33) provides more information about holes. 


is optional and specifies a value for filling holes in the section. 
See Section 9.12 (page 9-33) for more information about fill 
values for holes. 


Is optional and specifies that an output section should be al- 
located into a memory range that was named by the MEMORY 
directive. Section 9.7.4 (page 9-20) discusses named memory. 


Figure 9-7 shows how the sections in Figure 9-6 (page 9-16) are allocated. 
Figure 9-6 defines four output sections, .text, .data, init, and .bss: 


@ The .text output section combines the .text sections from filel.obj 
and file2.obj. Notice that the braces ({ }) are empty in this section 
specification; this tells the linker to include all input sections that have 
the same name as the output section. 


An address was specified for this output section; this causes the .text 
output section to begin at address 01000h in the target memory (this is 
known as binding). 


@ The .data output section contains the .data section from filel.obj. 


@ The init section is composed of the init (named) section in filel.obj 
and the .data section in file2.obj. 
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@ The .bss output section is composed of the .bss sections from 


filel.obj and file2.obj. This output section will be aligned on the 
next available 16-word boundary. 


Object Module 


text output section; 
must start at address 1000h 
in memory 


\ .data ouput section 


init output section 


.bss output section; 
must be aligned on a 
16-word address in memory 


Figure 9-7. Section Allocation Defined by Figure 9-6 


9.7.3 Specifying Input Sections 


An input section specification identifies the sections from input files that are 
combined to form an output section. The linker combines input sections by 
concatenating them in the order in which they are specified. The size of an 
output section is the sum.of the sizes of the input sections that make up the 
output section. 


Figure 9-8 shows the most common type of section specification; note that 
no input sections are listed. 


SECTIONS 
{ 


etext 


-data 
-bss 


Figure 9-8. The Most Common Method of Specifying Section 
Contents 


In the example shown in Figure 9-8, the linker takes all the .text sections from 
the input files and combines them into the .text output section. The linker 
concatenates the .text input sections in the order that it encounters them in the 
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input files. The linker performs similar operations with the .data and .bss sec- 
tions. You can use this type of specification for any output section. 


You can explicitly specify the input sections that form an output section. Each 
input section is identified by its filename and section name: 


SECTIONS 
{ 
JPext. /* Build .text output section * / 
{ 
f£1<0b7 CEext) 7/* Link .text section from fl.obj */ 
£2.0bj3(secl) 7/* Link secl section from £2.o0bj ef 
£3.0b3 /* Link ALL sections from f£3.o0bj * 


f4.obj(.text, sec2) /* Link .text and sec2 from f4.o0bj */ 
} 
3 


Note that it is not necessary for input sections to have the same name as each 
other or of the output section they become part of. If a file is listed with no 
sections, all of its sections are included in the output section. If any additional 
input sections have the same name as an output section, but are not explicitly 
specified by the SECTIONS directive, they are automatically linked in at the 
end of the output section. For example, if the linker found more .text sections 
in the preceding example, and these .text sections were not specified any- 
where in the SECTIONS directive, then the linker would concatenate these 
extra sections after £4.0bj(sec2). 


The specifications in Figure 9-8 are actually a shorthand method for the fol- 
lowing: 


SECTIONS 

{ 
etext : { ¥*(.text) } 
-data : { *(.data) } 
.bss ;: { *(.bss) } 

} 


The *(.text) means the unallocated .text sections from all the input files. 
This format is useful when: 


@ You want the output section to contain all input sections that have a 
certain name, but the output section name is different from the input 
sections’ name. 


@ You want the linker to allocate the input sections before it processes 
additional input sections or commands within the braces. 


Here’s an example that uses this method: 


SECTIONS 
{ 
.text : { 
abc.obj (xqt) 2 
*( text) 
} 
-data : { 
*(. data) 
fil.obj (table) 
} 
} 
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In this example, the .text output section contains a named section xqt from 
file abc.obj, which is followed by a// the .text input sections. The .data sec- 
tion contains a// the .data input sections, followed by a named section table 
from the file £fil.obj. Note that this method includes all the una/located 
sections. For example, if one of the .text input sections was already included 
in another output section when the linker encountered *(.text), the linker 
could not include that first .text input section in the second output section. 


9.7.4 Specifying the Address of an Output Section (Allocation) 
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After you specify the contents of each output section, you must identify the 
physical location in target memory where you want to load the section. Each 
section has an address field in its section header that tells a loader where the 
section should go. The process of calculating the address of the output sec- 
tions is called allocation. 


If you do not specify an explicit starting address for an output section, the 
linker uses a default algorithm to allocate the section. Generally, the linker 
puts sections wherever they fit into configured memory. 


You can override this default allocation by telling the linker where a section 
should be loaded. You can use three methods to control section allocation: 


e Binding 


You can supply a specific starting address for an output section by fol- 
lowing the section name with an address: 


.text 01000h : { ... } 


This example specifies that the .text section must begin at location 
1000h. The binding address must be a 24-bit constant. 


Output sections can be bound anywhere in configured memory (as- 
suming there is enough space), but they cannot overlap. If there is not 
enough space to bind a section to a specified address, the linker issues 
an error message. 


Note that you cannot bind a section to an address if you use alignment 
or named memory. \f you try to do this, the linker issues an error mes- 
sage. 


@ Alignment 


You can tell the linker to place an output section at an address that falls 
on an n-word boundary, where n is a power of 2. For example, 


SECTIONS 
{ 
-data ALIGN(32) : {£ ... } 


In this example, the .data output section is not bound to a specific ad- 
dress; it is linked at the next available address in configured memory that 
is a multiple of 32 words. 
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The assembler also supports a method for specifying alignment. The 
.align assembler directive allows you to align code or data on a 32-word 
(cache) boundary. When you use .align, the assembler sets a flag that 
tells the linker to align the entire section. This ensures that all the 
alignments within the section are correct when the section is relocated. 


@ Named Memory 


You can allocate a section into a memory range that was defined by the 
MEMORY directive. This example names ranges and links sections into 


them. 
MEMORY 
{ 
ROM (RIX) : origin = Oh, length = 1000h 
RAM (RWIX): origin = 3000h, length = 1000h 
} 
SECTIONS 
{ 
-text : { ... } > ROM 
.data ALIGN(64) : { ... } > RAM 
-bss : { ... } > RAM 


} 


In this example, the linker places the .text into the area called ROM. The 
.data and .bss output sections are allocated into RAM. You can align a 
section within a named memory range; the .data section is aligned on a 
64-word boundary within the RAM range. 


Similarly, you can link a section into an area of memory that has partic- 
ular attributes. To do this, specify a set of attributes (enclosed in pa- 
rentheses) instead of a memory name. Using the same MEMORY 
directive declaration, you can specify: 


SECTIONS 

{ 
etext: €s.<3 > {X) /* .text --> executable memory Bw 
-data: {...} > (RI) /* .data --> read or init memory */ 
-bss : {...} > (RW) /* .bss --> read or write memory */ 


} 


In this example, the .text output section can be linked into either the 
ROM or RAM area because both areas have the X attribute. The .data 
section can also go into either ROM or RAM because both areas have 
the R and | attributes. The .bss output section, however, must go into 
the RAM area because only RAM was declared with the W attribute. 


You cannot control where in the named memory range a section is allo- 
cated, although the linker uses lower memory addresses first and avoids 
fragmentation when possible. !n the preceding examples, assuming no 
other sections had been bound to addresses that would interfere with 
this allocation process, the .text section would start at address O. If a 
section must start on a specific address, use binding instead of named 
memory. 
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9.7.5 Grouping Output Sections Together 
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The SECTIONS directive has a GROUP option that forces several output sec- 
tions to be allocated contiguously. For example, assume that a section named 
term_rec contains a termination record for a table in the .data section. You 
can force the linker to allocate .data and term_rec together: 


SECTIONS 
{ 
-text : { } /* Normal output section * / 
-bss : { } /* Normal output section * / 
GROUP 1000h : /* Specify a group of sections i 
{ 
-data : { 3} /* First section in the group * 
term_rec : { } /* Allocated immediately after .data */ 


} 


You can use binding, alignment, or named memory to allocate a GROUP in the 
same manner as a single output section. In the preceding example, the 
GROUP is bound to address 1000h. This means that .data is allocated at 
1000h, and term—rec follows it in memory. 


Note: 


When you use the GROUP option, binding, alignment, or allocation into 


named memory can be specified for the group only. You cannot use 
binding, named memory, or alignment for sections within a group. 
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9.8 Overlay Pages 


Some target systems use an overlay memory configuration in which all or part 
of the memory space is overlayed by “shadow” memory. This allows the sys- 
tem to map different banks of physical memory in and out of a single address 
range in response to hardware selection signals. In this situation, multiple 
areas of physical memory overlay each other at one address space. You may 
want the linker to load various output sections into each of these areas or into 
areas that are not mapped at load time. 


The linker supports this feature by providing overlay pages. Overlay pages 
allow you to define a memory model that has multiple address spaces. To the 
linker, each possible overlay configuration represents a separate address space. 
Each address range is treated as a separate page and must be configured se- 
parately with the MEMORY directive. You can then use the SECTIONS di- 
rective to specify which sections will be mapped into various pages. 


9.8.1 Using the MEMORY Directive to Define Overlay Pages 


Each separately configured address space is called a page. To the linker, each 
page represents a completely separate memory that has the full 24-bit range 
of addressable locations. This allows you to link two or more sections at the 
same (or overlapping) addresses /f they are on different pages. 


Pages are numbered sequentially, beginning with 0. Page O represents the 
“normal” address space of the TMS320C30. The default memory model re- 
sides entirely on page O. If a memory range is specified without a page num- 
ber, the linker assumes it is in page 0. This allows you to ignore the page 
feature for most cases; usually all sections can be linked in page O with no 
overlays. 7 


For example, assume that your system can select between three 4K banks of 
physical memory to map into the address space from 100Q0h to 2000h. AIl- 
though only one bank can be selected at a time, you can initialize each bank 
with different data. Assume you have three output sections called sectoO, 
sectl, and sect2 that must be linked into the three banks of memory. This 
is how you would use the MEMORY directive to obtain this configuration: 


[BE REREREREEEREREREREREEREEEREREEREEREREEKERERERERERKRER / 


Yeas Example of MEMORY directive with overlay pages ues 
REKKEEEEREKEEEEREREREEERKEEEERERRERERERERREREREEERERERER / 


MEMORY 
{ 
PAGE 0: ROM : Origin = Oh, length = 1000h 
RAM : Origin = 100000h, length = OFOOOOOh 
OVR—MEM : origin = 1000h, length = 1000h 
PAGE 1: OVR-~MEM : origin = 1000h, length = 1000h 
PAGE 2: OVR—MEM : origin = 1000h, length = 1000h 


} 


Figure 9-9 (page 9-24) illustrates this configuration; it shows each available 
block of physical memory in the system and the section that must be loaded 
into it. 
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Page 0 Pagel | Page 2 
Oh wine oe ane ane 


OFFFh E:: 
1FFFh Lb: 


100000h f=: 


OFFFFFFh L:, 


Figure 9-9. Overlay Page Example 


This example defines three separate address spaces. Page O is the “normal” 
address space of the TMS320C30. It contains the memory ranges ROM and 
RAM; suppose they represent all the memory in the normal address space. Page 
0 also contains the first bank of overlay memory (OVR-MEM). The other two 
address spaces contain only the additional banks of overlay memory, both la- 
beled OVR-MEM. Note that all three OVR-MEM ranges cover the same address 
range. This is possible because each range is on a different page and therefore 
represents a different memory space. 


9.8.2 Using Overlay Pages with the SECTIONS Directive 
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-text: 
-data: 
-OSS : 
secto: 
sectl: 
sect2: 


The SECTIONS directive allows you to tell the linker which page an output 
section should be linked into. Each output section of the program is assigned 
a page as well as an address. You can assign an output section to an overlay 
page by following the section specification with the PAGE option and a page 
number. Continuing the example from the previous discussion, the SEC- 
TIONS definition would be: 


SECTIONS 
{ 


{} > ROM /* Link .text in ROM on page 0 * 

{} > RAM /* Link .data in RAM on page 0 * / 
{} > RAM /* Link .bss in RAM on page 0 * / 
{} > OVR_MEM PAGE 0 /* Link sectO into bank 0 (page 0) */ 
{} > OVR-MEM PAGE 1 /* Link sectli into bank 1 * / 
{} > OVR_MEM PAGE 2 /* Link sect2 into bank 2 */ 


lf you don’t specify a page number for an output section, the linker assumes 
page 0. In this example, .text, .data, and .bss are all linked into the named 
memory areas on page 0. (The PAGE O could have been omitted from the 
sectO definition as well.) 


The PAGE specifications for sect0, sectl1, and sect2 tell the linker to link 
these output sections into the corresponding overlay pages. As a result, they 
all are linked to address 1000h, but in different memory spaces. When the 
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9.8.3 Page 


program is loaded, a loader can configure hardware in such a way that each 
of these sections is loaded into the appropriate bank of memory. 


Within a page, you can bind output sections or use named memory areas in 
the usual way. In the preceding example, notice how sect1 is allocated into 
the memory range OVR_MEM. This allows you to define the allocation of sec- 
tions within a page, just as you can in a single memory space. 


For example, the following statement: 
sectl 1200h: {} PAGE 1 


links sect1 at address 1200h in page 1. If you do not specify any binding 
or named memory range for the section, the linker allocates the section into 
the page wherever it can (just as it normally does with a single memory 
space). For example, sect2 could also be specified as: 


sect2 : {} PAGE 2 


Because OVR—MEM is the only memory on page 2, it is not necessary (but ac- 
ceptable) to specify >OVR_MEM for the section. 


Definition Syntax 


As illustrated in the preceding examples, overlay pages are specified in the 
MEMORY directive by using the following syntax: 


MEMORY 


PAGE 0: memory range 
memory range 


PAGE rn: memory range 
memory range 


} 


Each page is introduced by the keyword PAGE and a page number, followed 
by a colon and a list of memory ranges the page contains. Memory ranges are 
specified in the normal way. You can define up to 255 overlay pages. Be- 
cause each page represents a completely independent address space, memory 
ranges on different pages can have the same name. Configured memery on 
any page can overlap configured memory on any other page. Within a single 
page, however, all memory ranges must have unique names and must not 
overlap. 


Any memory ranges listed outside the scope of a PAGE specification default 
to page 0. Consider the following example: 


ee 
ROM : org = Oh len = 1000h 
EPROM : org = 1000h len = 1000h 
RAM : org = 2000h len = QEOOOh 
PAGE 1: XROM : org = Oh len = 1000h 
XRAM : org = 2000h len = OEOOOh 


} 


The memory ranges ROM, EPROM, and RAM are ail on page O (because no page 
is specified). | XROM and XRAM are on page 1. Note that XROM on page 1 
overlays ROM on page 0 and XRAM on page 1 overlays RAM on page 0. 
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In the output link map (obtained with the -m linker option), the listing of the 
memory model is keyed by pages. This provides you with an easy method of 
verifying that you specified the memory model correctly. Also, the listing of 
output sections has a PAGE column that identifies the memory space into 
which each section will be loaded. 
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9.9 Default Allocation 


The MEMORY and SECTIONS directives provide flexible methods for build- 
ing, combining, and allocating sections. However, any memory locations or 
sections that you choose not to specify must still be handled by the linker. 
The linker has default algorithms that it uses to build and allocate sections, 
within the specifications you supply. Section 9.9.1 and Section 9.9.2 describe 
default allocation algorithms. 


9.9.1 Allocation Algorithm 


If you do not use the MEMORY directive, the linker assumes that the full 
24-bit address space is configured and allocates output sections into memory 
beginning at address 0. 


If you do not use the SECTIONS directive, the linker allocates the output 
sections as though the following SECTIONS directive was specified: 


SECTIONS 

{ 
text { } 
data { } 
bss { } 


} 


All .text input sections are concatenated to form a .text output section in the 
executable output file. All .data input sections are combined to form a .data 
output section, and all .bss sections are combined to form a .bss output sec- 
tion. Each output section is then allocated into configured memory. 


lf the input files contain named sections the linker links them in after the .bss 
section. Input sections that have the same name are combined into a single 
output section with this name. 


Note: 


When you use the SECTIONS directive, the linker performs no part of the 
default allocation. Allocation is performed according to the rules specified 
by the SECTIONS directive and the rules discussed in Section 9.9.2. 


9.9.2 General Rules for Output Sections 
An output section can be formed in one of two ways: 
Rule 1: As the result of a SECTIONS directive definition. 


Rule 2: By combining input sections with the same names into output 
sections that are not defined in a SECTIONS directive. 


If an output section is formed as a result of a SECTIONS directive (rule 1), this 
definition completely determines its contents. (See Section 9.7, page 9-16, 
for examples of how to specify the contents of output sections.) 


An output section can also be formed when input sections are encountered 
that are not specified by any SECTIONS directive (rule 2). In this case, the 
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linker combines all such input sections that have the same name into an out- 
put section with this name. For example, suppose the files £1.ob 3 and 
£2.obj both contain named sections called Vectors and that the SEC- 
TIONS directive does not define an output section to contain them. The linker 
will combine the two Vectors sections from the input files into a single out- 
put section named Vectors, allocate it into memory, and include it in the 
output file. 


After the linker determines the composition of all the output sections, it must 
allocate them into configured memory. The MEMORY directive specifies 
which portions of memory are configured, or if there is no MEMORY directive, 
the linker uses the default configuration. 


The linker’s allocation algorithm attempts to minimize memory fragmentation. 
This allows memory to be used more efficiently and increases the probability 
that your program will fit into memory. This is the algorithm: 


1) Any output section for which you have listed a specific binding address 
is placed in memory at that address. 


2) Any output section that is included in a specific named memory range 
or that has memory attribute restrictions is allocated. Each output sec- 
tion is placed into the first available space within the named area, con- 
sidering alignment where necessary. 


3) Any remaining sections are allocated in the order in which they were 
defined. Sections not defined in a SECTIONS directive are allocated in 
the order in which they were encountered. Each output section is placed 
into the first available memory space, considering alignment where nec- 
essary. 
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9.10 Special Section Types (DSECT, COPY, and NOLOAD) 


You can assign three special types to output sections: DSECT, COPY, and 
NOLOAD. These types affect the way that the program is treated when it is 
linked and loaded. You can assign a type to a section by placing the type 
(enclosed in parentheses) after the section definition. For example, 


SECTIONS 

{ 
secl 200000h (DSECT) : {f1l.obj} 
sec2 400000h (COPY) 3 <E£2.0b7 3 
sec3 600000h (NOLOAD) : {f£3.0bj} 

} 


© The DSECT type creates a "dummy section” with the following qualities: 


= It is not included in the output section memory allocation. It takes 
up no memory and is not included in the memory map listing. 


= It can overlay other output sections, other DSECTs, and uncontfig- 
ured memory. 


a Global symbols defined in a dummy section are relocated normally. 
They appear in the output module’s symbol table with the same 
value they would have if the DSECT had actually been loaded. 
These symbols can be referenced by other input sections. 


— Undefined external symbols found in a DSECT cause specified ar- 
chive libraries to be searched. 


- The section’s contents, relocation information, and line number 
information are not placed in the output module. 


In the preceding example, none of the sections from f£1.0bj are allo- 
cated, but all the symbols are relocated as though the sections were 
linked at address 200000h. The other sections can refer to any of the 
global symbols in secl. 


6 A COPY section is similar to a DSECT section, except that its contents 
and associated information are written to the output module. The .cinit 
section that contains initialization tables for the C compiler has this at- 
tribute under the RAM model. 


® A NOLOAD section differs from a normal output section in one respect: 
the section’s contents relocation information and line number informa- 
tion are not placed in the output module. The linker allocates space for 
the section, the section is listed in the memory map listing, etc. 
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9.11 Assigning Symbols at Link Time 


Linker assignment statements allow you to define external (global) symbols 
and assign values to them at link time. You can use this feature to assign an 
allocation-dependent value to a variable or a pointer. 


9.11.1 Syntax of Assignment Statements 


The syntax of assignment statements in the linker is similar to that of C as- 
signment statements: 


symbol = _ expression; Assigns the value of expression to symbol 
symbol = expression; Adds the value of expression to symbol 
symbol -= expression; Subtracts the value of expression from symbol 
symbol *=_ expression; Multiplies symbol by expression 

symbol /= _ expression; Divides symbol by expression 


The symboi should be defined externally in the program. If it is not, the linker 
defines a new symbol and enters it into the symbol table. The expression must 
follow the rules defined in Section 9.11.3. Assignment statements must be 
terminated with a semicolon. 


The linker processes assignment statements after it allocates all the output 
sections. Thus, if an expression contains a symbol, the address used for that 
symbol reflects the symbol’s address in the executable output file. 


For example, suppose a program reads data from one of two tables identified 
by two external symbols, Tablel and Table2. The program uses the symbol 
cur—tab as the address of the current table; cur_tab must point to Tabiel 
or Table2. You could accomplish this in the assembly code, but you would 
need to reassemble the program in order to change tables. Instead, you can 
use a linker assignment statement to assign cur —tab at link time: 


prog.obj /7* Input file * 
cur—_tab = Tablel; /* Assign cur—tab to one of the tables */ 


9.11.2 Assigning the SPC to a Symbol 
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A special symbol, denoted by a dot (.), represents the current value of the SPC 
during allocation. The linker’s ”.” symbol is analogous to the assembler’s “S$” 
symbol. The ”.” symbol can only be used in assignment statements within a 
SECTIONS directive, because ”.” is only meaningful during allocation, and the 
allocation process is controlled by the SECTIONS directive. 


For example, suppose a program needs to know the address of the beginning 
of the .data section. You can create an external undefined variable Dstart in 
the program by using the .global directive. Then, assign the value of ”.” to 
Dstart: 


SECTIONS 
{ 
swext-: 


i 
-data: { Dstart = .; } /* Dstart = current SPC value */ 
-bss : { 


This defines Dstart to be the ultimate linked address of the .data section. 
The linker will relocate all references to Dstart. 
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A special type of assignment assigns a value to the ”.” symbol. This adjusts 
the location counter within an output section and creates a hole between two 
input sections. Any value assigned to ”.” to create a hole is relative to the 
beginning of the section, not to the address actually represented by ”.”. As- 


“wow 


signments to ”.” and holes are described in Section 9.12. 


9.11.3 Assignment Expressions 


These rules apply to linker expressions: 


& Expressions can contain global symbols, constants, and the C language 
operators listed in Table 9-2. 


@ Ail numbers are treated as long (32-bit) integers. 


@ Constants are identified in the same manner as they are by the assembler. 
That is, numbers are recognized as decimals unless they have a suffix (H 
or h for hexadecimal and QO or q for octal). C language prefixes are also 
recognized (0 for octal and Ox for hex). Hexadecimal constants must 
begin with a digit. No binary constants are allowed. 


@ Symbols within an expression have only the value of the symbol’s ad- 
dress. No type checking is performed. 


@ Linker expressions can be absolute or relocatable. If an expression 
contains any relocatable symbols (and zero or more constants or abso- 
lute symbols), it is relocatable. Otherwise, the expression is absolute. 
if a symbol Is assigned the value of a relocatable expression, the symbol 
is relocatable; if assigned the value of an absolute expression, the symbol 
is absolute. 


The linker supports the C language operators listed in Table 9-2 in order of 
precedence. Operators in the same group have the same precedence. 


Besides the operators listed in Table 9-2, the linker also has an a/ign operator 
that allows a symbol to be aligned on an n-word boundary within an output 
section (rn is a power of 2). For example, the expression: 


= align(16) ; 


aligns the SPC within the current section on the next 16-word boundary. 
Because the align operator is a function of the current SPC, it can only be used 
in the same context as ”.” - that is, within a SECTIONS directive. 
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Group 1 (Highest Precedence) 


| Logical Not 
Bitwise Not Bitwise AND 
a ee 


a. Multiplication 
/ | Division Bitwise OR 
ar ane Mod 
Addition 
= Pe Tene 
>> | Arithmetic pap Grou shift | 
<< le errr left shift Logical OR 


Table 9-2. Operators in Assignment Expressions 


| = Group7 iY | = Group7 iY 


| Group8—sisdYd | Group8—sisdYd 


Group 10 (Lowest Precedence) 


ap en eS to 
Not equal to 

Greater than 

Less than 

Less than or equal to 

| Greater than or equal to 


II 


Assignment 
A+=B > A=A+B 
A-=B ~ A=A-B 
A*=B > A=A*B 
A/=B ~ A=A/B 


+ 


Hou dt a 


—™ of 


9.11.4 Symbols Defined by the Linker 


The linker automatically defines three symbols that a program can use at run 
time to determine where a section is linked. These symbols are external, so 
they appear in the link map. They can be accessed in any assembly language 
module if they are declared with a .global directive. 
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Values are assigned to these symbols as follows: 


text 


etext 


.data 


edata 


.bss 


end 


cinit 


is assigned the first address following the .text output section. 
(It marks the beginning of executable code.) 


is assigned the first address following the .text output section. 
(It marks the end of executable code.) 


is assigned the first address following the .data output section. 
(It marks the beginning of initialized data tables.) 


is assigned the first address following the .data output section. 
(It marks the end of initialized data tables.) 


is assigned the first address of the .bss output section. 
(It marks the beginning of uninitialized data.) 


is assigned the first address following the .bss output section. 
(It marks the end of uninitialized data.) 


is assigned the first address of the .cinit section (when -c or -cr is 
used). 


Linker Description — Creating and Filling Holes 


9.12 Creating and Filling Holes 


The linker provides you with the ability to create areas w/thin output sections 
that have nothing linked into them. These areas are called holes. In special 
cases, uninitialized sections can also be treated as holes. This section de- 
scribes how the linker handles such holes and how you can fill holes (and 
uninitialized sections) with a value. 


9.12.1 Initialized and Uninitialized Sections 


There are two rules to remember about the contents of an output section. An 
output section contains: 


Rule 1: Raw data for the entire section or 
Rule 2: No raw data. 


A section that has'raw data is referred to as initialized. This means that the 
object file contains the actual memory image contents of the section. When 
the section is loaded, this image is loaded into memory at the section's speci- 
fied starting address. The .text and .data sections always have raw data if 
anything was assembled into them. Named sections defined with the .sect or 
.asect assembler directives also have raw data. 


By default, the .bss section and .usect sections have no raw data (they are 
uninitialized). They occupy space in the memory map, but have no actual 
contents. Uninitialized sections typically reserve space in RAM for variables. 
In the object file, an uninitialized section has a normal section header and may 
have symbols defined in it; however, no memory image Is stored in the section. 


9.12.2 Creating Holes 


You can create a hole in an initialized output section. A hole is created when 
you force the linker to leave extra space between input sections when building 
an output section. When such a hole is created, the /inker must follow rule 7 
and supply raw data for the hole. 


Holes can only be created within output sections. There can also be space 
between output sections, but such spaces are not holes. There is no way to 
fill or initialize space between output sections. 


To create a hole in an output section, you must use a special type of linker 
assignment statement within an output section definition. The assignment 
statement modifies the SPC (denoted by ”.”) by either adding to it, assigning 
a greater value to it, or aligning it to an address boundary. The operators, ex- 
pressions, and syntax of assignment statements are described in Section 9.11 
(page 9-30). 
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The following example shows how holes can be created in output sections 
using assignment statements: 


pee 
oot 
filel.obj(.text) 
. += 100h; /* Create a hole with size 100h * / 
file2.obj(.text) 
- = align(16); /* Create a hole to align the SPC */ 
file3.obj 


} 


The output section outsect is built as follows: 


The .text section from filel.obj is linked in. 
The linker creates a 256-word hole. 
The .text section from file2.obj is linked in after the hole. 


The linker creates another hole by aligning the SPC on a 16-word 
boundary. 


@ Finally, the .text section from file3.obj is linked in. 


wee 


All values assigned to the ”.” symbol within a section refer to the re/ative ad- 
dress within the section. The linker handles assignments to the ”.” symbol as 
if the section started at address O (even if you specify a binding address). 
Consider the statement . = align(16) in the preceding example. This 
statement effectively aligns file3.obj .text to start on a 16-word boundary 
within outsect. If outsect is ultimately allocated to start on an address that 
is not aligned, then £ile3 .text will not be aligned either. 


Expressions that decrement ”.” are illegal. For example, it is invalid to use the 
-= operator in an assignment to ”.”. The most common operators used in as- 


wseag 


signments to ”.” are += and align. 


If an output section contains all input sections of a certain type (such as .text), 
you can use the following statements to create a hole at the beginning or end 
of the output section: 


etext: { .+= 100h; } /* Hole at the beginning */ 
.data: f 
*(.data) 
+=100h; 3 /* Hole at the end = 


Another way to create a hole in an output section is to combine an uninitial- 
ized section with initialized sections to form a single output section. /n this 
case, the linker treats the uninitialized section as a hole and supplies data for 
it. An example of creating a hole in this way is: 


SECTIONS 
{ 
outsect: 


filel.obj(.text) 
filel.obj(.bss) /* This becomes a hole */ 


} 


Because the .text section has raw data, all of outsect must also contain raw 
data (rule 1). Therefore, the uninitialized .bss section becomes a hole. 
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Note that uninitialized sections only become holes when they are combined 
with initialized sections. If multiple uninitialized sections are linked together 
the resulting output section is also uninitialized. 


9.12.3 Filling Holes 


Whenever there is a hole in an initialized output section, the linker must supply 
raw data to fill it. The linker fills holes with a 4-byte fill value that is replicated 
through memory until it fills the hole. The linker determines the fill value as 
follows: 


1) 


2) 


3) 


4) 


lf the hole is formed by combining an uninitialized section with an ini- 
tialized section, you can specify a fill value for that specific initialized 
section. Follow the section name with an = symbol and a 4-byte con- 
stant: 


SECTIONS 
{ 
outsect: 


filel.obj(.text) 
file2.obj(.bss) = OFFh /* Fill this hole */ 
3 /* with OOOOOOFFh */ 


You can also specify a fill value for all the holes in an output section by 
supplying the fill value after the section definition. For example, 


pee 
outsect: 
{ 
. += 10h; /* This creates a hole eS. 
filel.obj(.text) 
filel.obj(.bss) /* This creates another hole #*/ 
3} = OFFOOh /* This fills both holes with */ 
3 /* OOOOFFOOh */ 


If you do not specify an initialization value for a hole, the linker fills the 
hole with the value specified with -f. For example, suppose the com- 
mand file link. cmd contains the following SECTIONS directive: 


SECTIONS 
{ 


-text: { .= 100; } /* Create a 100-word hole */ 
} 


Now invoke the linker with the -f option: 
1nk30 -f OFFFFFFFFh link.cmd 


This fills the hole with OFFFFFFFFh. 


If you do not invoke the linker with -f, the linker fills holes with Os. 


Whenever a hole is created and filled in an initialized output section, the hole 
is identified tn the link map along with the value the linker uses to fill it. 
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9.12.4 Explicit Initialization of Uninitialized Sections 
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An uninitialized section only becomes a hole when it is combined with an in- 
itialized section. When uninitialized sections are combined with each other, 
the resulting output section remains uninitialized and has no raw data in the 
output file. 


However, you can force an uninitialized section to be initialized simply by 
specifying an explicit fill value for it in the SECTIONS directive. This causes 
the entire section to have raw data (the fill value). For example, 


SECTIONS 
{ 
-bss: {} = 11223344h /* Fills .bss with 11223344h */ 


Note: 


Because filling a section (even with Os) causes raw data to be generated 
for the entire section in the output file, your outcut file will be very large 
if you specify fill values for large sections or holes. 


Linker Description - Partial (Incremental) Linking 


9.13 Partial (Incremental) Linking 


An output file that has been linked can be linked again with additional mod- 
ules. This is known as partial linking or incremental linking. Partial linking 
allows you to partition large applications, link each part separately, and then 
link all the parts together to create the final executable program. 


Follow these guidelines for producing a file that you will relink: 


Intermediate files must have relocation information. Use the -r option 
when you link the file the first time. 


Intermediate files must have symbolic information. By default, the linker 
retains symbolic information in its output. Do not use the -s option tf 
you plan to relink a file, because -s strips symbolic information from the 
output module. 


Intermediate link steps should only be concerned with the formation of 
output sections, and not with allocation. All allocation, binding, and 
MEMORY directives should be performed in the final link. 


The following example shows how you can use partial linking. 


© Step 1: Link the file £ilel.com; use the -r option to retain relocation infor- 
mation in the output file tempoutl.out. 


1nk30 -r -o tempoutl filel.com 


filel.com contains: 


SECTIONS 


} 


ssl:{ 


£1. 0b7 
£2.07 


fn.ob3 
} 


@ Step 2: Link the file £ile2.com; use the -r option to retain relocation infor- 
mation in the output file tempout2.out. 


1nk30 -r -o tempout2 file2.com 


file2.com contains: 


acca 


3 


ss2:{ 


glwobj 
g2.o0b] 


gn.obj 


@ Step 3: Link tempoutl.out and tempout2.out: 


1nk30 -m final.map -o final.out tempoutl.out tempout2.out 
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9.14 Linking C Code 


The TMS320C30 C compiler produces assembly language source code that 
can be assembled and linked. For example, a C program consisting of mod- 
ules progl, prog2, etc., can be assembled and then linked to produce an 
executable file called prog.out: 


ink30 -c -o prog.out progl.obj prog2.obj ... rts.lib 


The -c option tells the linker to use special conventions that are defined by the 
C environment. The archive library rts.1lib contains C runtime support 
functions. 


For more information about-C, including the runtime environment and runtime 
support functions, see the 7MS320C30 C Compiler Reference Guide. 


9.14.1 Runtime Initialization 


All C programs must be linked with an object module called boot .ob3j, which 
contains code and data for initializing the runtime environment. 


When the program begins running, this code is executed first and performs the 
following actions: 


@ Sets up the system stack 
® Processes the runtime initialization table and autoinitializes global vari- 
ables (in the ROM model) 


& Disables interrupts and calls -main 


The runtime support object library, rts.1lib, contains boot.obj. You can 
use the archiver to extract boot .obj from the library, and then link it in di- | 
rectly, or you can simply include rts.1ib as an input file and the linker will 
extract boot .obj when you use the -c or -cr option. 


9.14.2 Object Libraries and Runtime Support 


The TMS320C30 C Compiler Reference Guide describes additional runtime 
support functions that are included in rts.lib. If your program uses any of 
these functions, you must link rts.1ib with your object files. 


You can also create your own object libraries and link them. The linker will 
include and link only those modules in a library that resolve undefined refer- 
ences. 


9.14.3 Autoinitialization (ROM and RAM Models) 
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The C compiler produces tables of data that are used to autoinitialize global 
variables. These are contained in a special section called .cinit. The initial- 
ization tables can be used for autoinitialization in either of two ways. 


@ ROM Model (-c option) 


Variables are initialized at run time. The .cinit section is loaded into 
memory along with all the other sections. The linker defines a special 
symbol called cinit that points to the beginning of the tables in mem- 


Linker Description - Linking C Code 


ory. When the program begins running, the C boot routine copies data 
from the tables into the specified variables in the .bss section. This al- 
lows initialization data to be stored in ROM and then copied to RAM 
each time the program is started. 


Figure 9-10 illustrates the ROM autoinitialization model. 


Object File Memory 


Initialization 


Tables 
(possibly ROM) 


Boot 
Routine 


Figure 9-10. ROM Model of Autoinitialization 


@ RAM Model (-cr option) 


Variables are initialized at /oad time. This can enhance performance by 
reducing boot time and can save memory used by the initialization ta- 
bles. (Note that you must use a smart loader to take advantage of the 
RAM model of autoinitialization.) 


When you use -cr, the linker marks the .cinit section with a special at- 
tribute. This attribute tells the linker not to load the .cinit section into 
memory. The linker also sets the cinit symbol to -1; this informs the 
C boot routine that initialization tables are not present in memory. Thus, 
no runtime initialization is performed at boot time. 


When the program is loaded, the loader must be able to: 
= Detect the presence of the .cinit section in the object file. 


= Detect the presence of the attribute that tells it not to copy the 
.cinit section. 


zs Understand the format of the initialization tables (this is described 
in the T7MS320C30 C Compiler Reference Guide). 


The loader then uses the initialization tables directly from the object file 
to initialize variables in .bss. 


Figure 9-11 (page 9-40) illustrates the RAM autoinitialization model. 
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Object File Memory 


Figure 9-11. RAM Model of Autoinitialization 


9.14.4 The -c and -cr Linker Options 
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The following list outlines what happens when you invoke the linker with the 
-C Or -cr option. 


The symbol —c—intoOO is defined as the program entry point. 
—c—int0O0 is the start of the C boot routine in boot.obj; referencing 


—c—int0OO ensures that boot.obj will automatically be linked in from 
the runtime support library rts.1lib. 


The .cinit output section is padded with a termination record so that the 
boot routine (ROM model) or the loader (RAM model) knows when to 
stop reading the initialization tables. 


In the ROM model (-c option), the linker defines the symbol cinit as 
the starting address of the .cinit section. The C boot routine uses this 
symbol as the starting point for autoinitialization. 


In the RAM model (-cr option): 


- The linker sets the symbol cinit to -1. This indicates that the 
initialization tables are not in memory, so no initialization is per- 
formed at boot time. 


- The STYP—COPY flag (010h) is set in the .cinit section header. 
STYP—COPY is the special attribute that tells the loader to perform 
autoinitialization directly and not to load the .cinit section into 


memory. The linker does not allocate space in memory for the .cinit 
section. 


Linker Description - Example 


9.15 Linker Example 


This example links three object files named demo.obj, fft.obj and ta- 
bles.obj and creates a program called demo.out. The symbol SETUP is the 
program entry point. 


Assume that target memory has the following configuration: 


Address Range Contents 
000000h to OOOFFFI 4K on-chip ROM 
801000h to 8013FFh Internal RAM block BO 
801400h to 801 7FFh Internal RAM block B1 


801800h to OFFFFFFh External RAM 


The output sections are constructed from the following input sections: 


@ A set of interrupt vectors from section int—vecs in the file tables.obj 
must be linked at address 0 in ROM. 


@ Executable code, contained in the .text sections of demo.obj and 
fft.obj, must also be linked into ROM. 


e Two tables of coefficients, which are in the .data sections of the files 


tables.obj and fft.obj must be linked into RAM block BO. The 
remainder of block BO must be initialized to the value OFFCC11 22h. 


@ The .bss section from f£t.obj, which contains variables, must be linked 
into block B1 of data RAM. The unused part of this RAM must be ini- 
tialized to OFFFFFFFFh. 


@ The .bss section from demo.obj, which contains buffers and variables, 
must be linked into external RAM. 


Figure 9-12 shows the linker command file for this example; Figure 9-13 
shows the map file. 
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fe A ae a Te OC eRe eR Tye We sR ee a ee a Oe eee Oe Be SIE ee Ce PON ee 


sis ies Specify Linker Options KK KK 
LREEERESESEEE ERE ER RARER LAELEA ERR EAEARERAER EAE AE ERAS REAR RARARA ARE EX / 


-e SETUP Define the entry point 
-o demo.out Name the output file 
-m demo.map Create a load map 


REKKEKEKKEKREEKKEKEREKERKRKREKRERKEREREKRRERERRERKKERREEKEEREKEKEERRREKRKREKEERRKRREREAE 


[RRR Specify the Input Files sal A 
(ICICI CII ICICI ICI TOC CICICT CIC CIIOCI TOI TOI IC CRTO COIR TOI TOR TOI TOI IR IORI 


demo.obj 
ft sObF 
tables.ob} 


KEKKKKEKKEKRERKREEEKEEKR ERE REE ERE ER EEE RE RE RE REE ERE RERE REE EERE REE EEEEREE / 


a Specify the Memory Configuration RAKE 
JL EEDEREILAL SARL RMA RR Rh Ne Ry RIN ee TORR PLAN, OR MT, MIE Ge Ne Fe ye 


MEMORY 
{ 


Q01000h 
0400h 
0400h 
O7FE800h 


ROM: origin 
RAMBO: origin 
RAM_B1: origin 
RAM origin 


0000000h length 
0801000h length 
0801400h length 
0801800h length 


KK KKK RR KR RK KER KR KK RE KR KEK RRR REE RRR RRR RRR ERE KR ER RE RRR ERR ER RR EK KERKKKEKEE 


loans: Specify the Output Sections KKK 
fRELAALSE TEESE EEE EAA LEA ERE ERASE RAR RAE SRE EAS AER SERA ARE RELA EA RE / 


SECTIONS 
{ 


-text: {} >ROM Link all .text sections into’ ROM 
int—_vecs Oh: {3 Link interrupts at 9 
.data: Link the .data sections 
tables.obj(.data) -data input section 
FEC Ob )(.deata) /* .data input section 
- = 400h; Create a hole to end of block 
} = OFFCC1122h > RAMBO /* Fill and link into BO 
fftvars: Create a new fftvars section 


Ett.0b7%.bss) 
= OFFFFFFFFh > RAM_B1 Fill and link into Bl 


-bss: {} >RAM Link all remaining .bss sections 


KEKE EKKEKEKREKEKEKKRERKERKERKEKERERERERKEERKEERERERKEKEREKRRKERRERKREKRREKREREKRKKRKKKEKKEKE 


KKKK End of Command File KKKK 
LEER ERLE EER Re SR OR ee eee Ce OR ieee RSE Me Oe le EN TN eS RN Re Re ete ef 


Figure 9-12. Linker Command File, demo.cmd 


Invoke the linker with the following command: 
1nk30 demo.cmd 


This creates the map file shown in Figure 9-13 and an output file called 
demo.out that can be run on the TMS320C30. 
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KRREKEKREKKEKRERREREKKEREKKKKERKRERKERERREREERERREKEKREKRKRKEKKRKRKEEKKEKERKEKKEKSE 


TMS320C30 COFF Linker, Version 1.00, 87.070 
KRREKEKERKEKKKEKKEKKEKEKKEKKREREKRKEKRKEREEKKEEKRKRKERKEKEEEKEKREKERKKEERKKKRKEKEKEESE 


OUTPUT FILE NAME: <demo.out> 


ENTRY POINT SYMBOL: "SETUP" address: 00000040 


MEMORY CONFIGURATION 
attributes 


000001000 
000000400 
000000400 
0007FE800 


00000000 
00801000 
00801400 
00801800 


SECTION ALLOCATION MAP 


attributes/ 


output 
input sections 


section page origin 
00000040 


00000040 


00000000 
Q0Q000000 


int—vecs 

demo.obj (int—vecs) 

000001B0 
OOOOO14E 
00000064 


00000040 
00000040 
OO00018E 


-text 
(text) 
(.text) 


demo .obj 
Filet: .oby 


00000400 
QOQO00A5 
00000014 
00000347 


00801009 
008010000 
0080100A5 
O0080100B9 


tables.obj (.data) 
fft.obj (.data) 
—“HOLE== (ELL = £iceciZ22] 


O000001A 
0000001A 


00801400 
00801400 


fftvars 


frt.ob} (.bss) [iill = ffELi tee | 
OOO00039A 


OOOQ009A 


UNINITIALIZED 
demo.obj (.bss) 


-bss 00801800 
00801800 


GLOBAL SYMBOLS 


address 


00000040 
00801400 
OO80180A 
QQO001F2 
00801800 
| QOOOOO8A 
00000166 
00000184 
00000170 
OQOOOLTA 
QOOO004A 
00000120 


[12 symbols] 


name 
SETUP 
edata 
end 
etext 
extvar 
TEL 
list 
main 
plasm 
p2asm 
start 
sub 


Figure 9-13. 


00000040 
OO00004A 
OO00008A 
00000120 
00000166 
00000170 
OOOOO17A 
00000184 
OOOOO1LF2 
00801400 
00801800 
0080189A 


name 
SETUP 
start 
1 a 
sub 
list 
plasm 
p2asm 
main 
etext 
edata 
extvar 
end 


Output Map File, demo.map 
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section 10 


Object Format Converter Description 


Most EPROM programmers do not accept COFF object files as input. The 
object format converter converts a COFF object file into one of three object 
formats that most EPROM programmers accept as input: 


e Tektronix hex object format 
@ Intel hex object format 


@ Ti-tagged object format 


The object format converter accepts one COFF object file as input. If you are 
converting to Tl-tagged object format, the utility produces one output file. If 
you are converting to Tektronix or Intel object format, the utility produces four 
Output files (one output file for each set of bytes, from least significant to 
most significant bytes). 


This section contains the following topics: 


Section Page 
10.1 Object Format Converter Development FIOW ..............ccccccceeeceeeeeeees 10-2 
10.2 Invoking the Object Format Converter ................:cc:ccsssseeeeesseessseeneees 10-3 
WOOD. TEXANVOI CS <5 chic sec acd So cages cara nate fea crsciaasncssyansian eee canieemaeion aaaeaaeaiaians 10-4 
VO Ax JAI CONGIONS rccececigacccmncactesaanewras disses tauicamadiactesenntavacmesagsocsatan aleve: 10-4 


Object Format Converter Description - Development Flow 


10.1 Object Format Converter Development Flow 


Figure 10-1 illustrates the object format converter’s role in the assembly lan- 
guage development process. 
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Source 
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Figure 10-1. Object Format Converter Development Flow 
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10.2 Invoking the Object Format Converter 


To invoke the object format converter, enter: 


rom30 /-option] [COFF input file] 


rom30 is the command that invokes the object format converter; all parame- 
ters are optional. 


The filename is the name of the file that you want to convert. If you do not 
specify an input filename, the object format converter prompts for one. If you 
specify a filename without an extension, the utility assumes that the filename 
has a default extension of .ob/. 


There are three options which can be entered anywhere on the line. The op- 
tions identify the format of the output file: | 


-i specifies Intel hex object format for the output. 
-t specifies Tl-tagged object format for the output. 
-x specifies Tektronix hex object format for the output. 


If you don’t supply an option, the object format converter produces Tektronix 
hex format output files. The object format converter uses the input filename 
(without it’s extension) to name output files; it chooses the file extension 
depending on the type of output you've requested: 


® For 7/-tagged format, the object format converter produces one output 
file with an extension of .tag. 


@ For /nte/ or Tektronix format, the object format converter produces four 
files with the following extensions: 


_ .60 is the extension for the file that contains the least significant 
bytes. 


- .67 is the extension for the file that contains the next-to-least 
significant bytes. 


- .62 is the extension for the file that contains the next-to-most 
significant bytes. 


= .63 is the extension for the file that contains the most significant 
bytes. 


When the object format converter finishes converting the input file, it prints 
the message Translation complete. 
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10.3 Examples 


Here are some examples of using the object format converter. 


Example 1: 


You can invoke the object format converter with no options and no 
filename: 


rom30 


The utility will print the following banner and prompt: 


COFF Object Converter Version 5.01, 87.610 
(c) Copyright 1987, Texas Instruments Inc. 


Coff file [.obj]: 


If, for example, you respond to the prompt with a filename of fft, the 
object format converter uses the file ££t.obj as an input file. It pro- 
duces four Tektronix-format output files named fft.bO, fft.bl, 
fft.b2,and fft.b3. 


Example 2: 
If you enter: 
rom30 -1i in 


the utility uses in. obj as the input file. It creates four Intel-format files 
named in.bO, in.bl, in.b2, and in.b3. 


Example 3: 


lf you enter: 


FOnsO- ins tmps =£ 


the object format converter uses in.tmp as the input file. It produces 
a single Tl-tagged output file named in.tag. 


10.4 Halt Conditions 


There are two situations in which the object format converter aborts exe- 
cution: 
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1) 


2) 


If any of the specified files cannot be opened, the code conversion utility 
prints the message Input COFF file cannot be opened and aborts. 


If you supply the utility with the name of an invalid object file, the object 
format converter prints the message Corrupt input file and aborts. 


Appendix A 


Common Object File Format 


The TMS320C30 assembler and linker create object files that are in common 
object file format (COFF). COFF ts an implementation of an object file format 
of the same name that was developed by AT&T for use on UNIX-based sys- 
tems. This object file format has been chosen because it encourages modular 
programming and provides more powerful and flexible methods for managing 
code segments and target system memory. 


One of the basic COFF concepts is sections. Section 3, Introduction to 
Common Object File Format, discusses COFF sections in detail. If you un- 
derstand section operation, you will be able to use the TMS320C30 assembly 
language tools more efficiently. 


This appendix contains technical details about COFF object file structure. 
Most of this information pertains to the symbolic debugging information that 
is produced by the TMS320C30 C compiler. The main purpose of this ap- 
pendix Is to provide supplementary information for those of you who are in- 
terested in the internal format of object files. 


Topics in this appendix include: 
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A.1 File Structure 


The elements of a COFF object file describe the file’s sections and symbolic 
debugging information. These elements include: 


co] A file header, 

Optional header information, 

A table of section headers, 

Raw data for each section (except .bss), 

Relocation information for each section (except .bss), 
Line number entries for each section (except .bss), 

A symbol table, and 

@ A string table. 


The assembler and linker produce object files with the same COFF structure; 
however, a program that is linked for the final time will not contain relocation 
entries. Figure A-1 illustrates the ovetall object file structure. 


Section Headers 


Raw Data 
(executable code 
and initialized data) 


Relocation Information 


Line Number 
Entries 


Figure A-1. COFF File Structure 
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Figure A-2 shows a typical example of a COFF object file that contains the 
three default sections, .text, .data, and .bss, and a named section (referred to 
as <named>). By default, the .text, .data, and .bss sections, respectively, are 
placed in the object file, followed by any named sections in the order in which 
they were encountered. Although the .bss section has a section header, no- 
tice that it has no raw data, no relocation information, and no line number 
entries; named sections created with .usect do not have this type of informa- 
tion, either. This is because the .bss and .usect directives simply reserve space 
for uninitialized data; their sections contain no actual code. 


Section 
Headers 


Raw 
Data 


Relocation 
information 


Line Number 
Entries 


Symbol Table 


String Table 


Figure A-2. Sample COFF Object File 
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A.2 File Header 


The file header contains 20 bytes of information that describe the general 
format of an object file. Table A-1 shows the structure of the file header. 


Table A-1. File Header Contents 
B 
0-1 Unsigned short integer Magic number (093h), indicates that the 
file can be executed in a TMS320C30 sys- 
tem 


: Unsigned short integer Number of section headers | 
4-7 Long integer | Time and date stamp, indicates when the | 
file was created 
8-11 Long integer File pointer, contains the symbol table’s | 
| starting address 


12-15 Number of entries in the symbol table 


16-17 Unsigned short integer | Number of bytes in the optional header. | 
This field is either O or 28; if it is 0, then | 
there is no optional file header. 


18-19 Unsigned short integer Flags (see Table A-2) 


Table A-2 lists the flags that can appear in bytes 18 and 19 of the file header. 
Any number and combination of these flags can be set at the same time (for 
example, if bytes 18 and 19 are set to 0003h, then F—RELFLG and F—EXEC 
are both set.) 


Table A-2. File Header Flags (Bytes 18 and 19). 


F_RELFLG | OOO1h | Relocation information was stripped from | 
| | the file 
—EXEC | 0002h | The file is executable(it contains no unre- | 
! | solved external references) | 


F 
F_LNNO 0004h | Line numbers were stripped from the file 
F 


_ FELSYMS_ [| 0010h | Local symbols were stripped from the file 


| F_AR32WR | 0040h | The file has the byte ordering used by the | 
| TMS320C30 support tools: (32 bits per 


Word) Jsest SIG BIMCaat DVIS HIST) os. 
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A.3 Optional File Header 


The linker creates the optional file header and uses it to perform relocation at 
download time. Partially linked files do not contain optional file headers. 
Table A-3 illustrates the optional file header format. 


Table A-3. Optional File Header Contents 


[ot | Short intager | __Magie number (010m) 
[23 [Short intager | Version stamp 
[a7 __Long integer | Size (in words) of executable code 
[eit [Long integer | Size (in words) of initialized words 
24-27 | Long integer | Beginning address of initialized deta 
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A.4 Section Headers 


COFF object files contain a table of section headers that specify where each 
section begins in the object file. Each section of the file has its own section 
header. 


Byte 
Number 


Table A-4. Section Header Contents 


as Eight-character section name, padded with 
nulls 


0-7 ” : 
8-11 | Longinteger = sd Section’s physical address 
15 | RE 


| 16-19 | Longinteger_ | Section size in words 
File pointer to raw data 
File pointer to line number entries 


3 
34-35 Unsigned short integer Number of line number entries | | 
36-37 Unsigned short integer Flags (see Table A-5) 


File pointer to relocation entries 


[38 | Character 
[39 [Character | Memory page number. 


Table A-5 lists the flags that can appear in bytes 36 and 37 of the section 
header. 


Table A-5. Section Header Flags (Bytes 36 and 37) 


| Mnemonic | Flag | Ci escription 
| STYP_REG 0000h | Regular section (allocated, relocated,loaded) | 
STYP—DSECT 0001h | Dummy section (relocated, not allocated, not loaded) 


Padding section (loaded, not allocated, not relocated) 


STYP—COPY 0010h | Copy section (not allocated, relocated, loaded; relo- 
cation and line number entries are processed normally) 


Note: The term /oaded means that the raw data for this section appears in the object file 


The flags listed in Table A-5 can be combined; for example, if the flags word 
is set to O24h, then both STYP—GROUP and STYP—TEXT are set. 
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Figure A-6 illustrates how the pointers in a section header would point to the 
various elements in an object file that are associated with the .text section. 


O- 8-11 12-15 16-19 20-23 24-27 28-31 32-33 34-35 36-37 38 39 


Section Header [_- TC A CS CE ET RE IE 


Figure A-3. An Example of Section Header Pointers for the .text Section 


As Figure A-2 (page A-3) shows, the .bss section and uninitialized sections 
defined with .usect vary from this format. Although there ts a section header 
for each uninitialized section, these sections have no raw data, no relocation 
information, no line number information, and occupy no actual space in the 
object file. Therefore, the number of relocation entries, the number of line 
number entries, and the file pointers in an uninitialized section header are zero. 
Section headers for uninitialized sections simply tell the linker how much 
space for variables it should reserve in the memory map. 
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A.5 Relocation Information 


A COFF object file has one relocation entry for each relocatable reference. 
The assembler automatically generates relocation entries. The linker reads the 
relocation entries as it reads each input section and performs relocation. The 
relocation entries determine how references within an input section are 
treated. 


The relocation information entries use the 10-byte format shown in Table A-6. 


Table A-6. Relocation Entry Contents 


Byte : | | ! 
eet onainicoae nual adees corte weterenes) | 
| AB 7 Unsigned short integer | Symbol table index (0-65535) 
[6-7 | Unsigned short integer_| Reseed 
| 8-9 | Unsigned short integer a Relocation type (see Table A-7) 


Table A-7 lists the relocation types that can appear in bytes 8 and 9 of the 
relocation entry. 


Tabie A-7. Relocation Types (Bytes 8 and 9) 


[Mnemonic | Flag [Relocation Type 
|_R-ABS | 0000h_| Norelocation 
| R-REL24 | 005h | 24-bit direct reference | 


| R_ | 

| R—RELWORD 0010h 16-bit direct reference to symbol’s | 
= | | address | 
| R-RELLONG {| 0011h | 32-bit direct reference to symbol’s | 
| | | address : 
| R— ; | 


TROGSPPCRIG | 0019h | 16-bit relative (in words) 
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A.6 Line Number Table 


The object file contains a table of line number entries that are useful for sym- 
bolic debugging. When the C compiler produces several lines of assembly 
language code, it creates a line number entry that maps these lines back to the 
Original line of C source code that generated them. Each single line number 
entry contains 6 bytes of information. Table A-8 shows the format of a line 
number entry. 


Table A-8. Line Number Entry Format 


Byte 


Long integer This entry may have one of two values: 

1) If it is the first entry in a block of line 
number entries, it points to a symbol 
entry in the symbol table 

| 2) If it is not the first entry in a block, it 
is the physical address of the line indi- 
cated by bytes 4-5 


Unsigned short integer This entry may have one of two values: 

1) If this field is 0, then this is the first line 
of a function entry 

2) If this field is not 0, then this is the line 

! number of a line of C source code 


Figure A-4 shows how line number entries are grouped into blocks. 


| Symbol index | 0 
physical address jie number 
physical address 


i a 
| physical address | line number | 


| physical address | line number __| 


Figure A-4. Line Number Biocks 


As Figure A-4 shows, each entry is divided into nalves: 


@ For the first fine of a function, 


se Bytes 0-3 point to the name of a symbol or a function in the 
symbol table. . 
= Bytes 4-5 contain a 0, which indicates the beginning of a block. 


8 For the remaining lines in a function, 


= Bytes 0-3 show the physical address (the number of words cre- 
ated by a line of C source). 

= Bytes 4-5 show the address of the originai C source, relative to fis 
appearance in the C source program. 


The line entry table can contain many of tness blocks. 
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Figure A-9 illustrates an example of line number entries for a function named 
XYZ. As shown, the function name is entered as a symbol in the symbol table. 
The first portion on XYZ’s block of line number entries points to the function 
name in the symbol table. Assume that the original function in the C source 
contained three lines of code. The first line of code produces 4 words of as- 
sembly language code, the second line produces 3 words, and the third line 
produces 10 words. Figure A-9 shows what the line number entries would 
look like for this example. 


Line Number 
Entries 


Symbo! Table 


Figure A-5. Line Number Entries Example 


(Note that the symbol table entry for xyz has a field that points back to the 
beginning of the line number block.) 


Since line numbers are not often needed, the linker provides an option (-s) 
that strips line number information from the object file. This provides a more 
compact object module. 
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A.7 Symbol Table 


The order of symbols in the symbol table is very important; they appear in the 
sequence shown in Figure A-3. 


Local symbols 

for Function 1 

Local symbols 

for Function 2 

Local symbols 

for Function 1 
Defined global symbols | 
Undefined global symbols 


Figure A-6. Symbol Table Contents 


Static variables refer to symbols defined in C that have storage class static 
outside any function. If you have several modules that use symbols with the 
same name, making them static confines the scope of each symbol to the 
module that defines it (this eliminates multiple-definition conflicts). 


The entry for each symbol in the symbol table contains the symbol’s: 


Name (or a pointer into the string table) 

Type | 

Value 

Section it was defined in 

Storage class 

Basic type (integer, character, etc.) 

Derived type (array, structure, etc.) 

Dimensions 

Line number of the source code that defined the symbol 


Section names are also defined in the symbol table. 
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All symbol entries, regardless of the symbol’s class and type, have the same 
format in the symbol table. Each symbol table entry contains the 18 bytes of 
information listed in Table A-9. Some symbols may not have all the charac- 
teristics listed above; if a particular field is not set, it will be set to null. 


Table A-9. Symbol Table Entry Contents 


Byt 


0-7 Character This field contains one of the following: 
| 1) An 8-character symbol name, padded 
with nulls 
| 2) A pointer into the string table if the 
symbol name is longer than 8 charac- 
| ters 


| 8-11 | Long integer Symbol value; storage class dependent___ 
| 16 | Character | Storage class of the symbol 


A.7.1 Special Symbols 


The symbo! table contains some ‘special symbols that are generated by the 
compiler, assembler, and linker. Each special symbol contains ordinary sym- 
bol table information as well as an auxiliary entry. Table A-10 lists these 
symbols. 


Table A-10. Special Symbols in the Symbol Table 


| _file =| Filename —eeses—“(‘“‘“‘“‘iéOO crt 
text Address of .text section — 


| bb Address of the beginning of a block | 


data Address of .data section 
Address of the end of a block 


| bss Address of .bss section | 


Address of the beginning of a function 


.bf 
.ef 


|__Pointer to a structure or union that is returned by a function __| 
|__Dummy tag name for a structure, union, or enumeration 
| of_a structure, union, or enumeration eee ee 
Next available address after the end of the .text output section 

Next available address after the end of the .data output section _| 
Next available address after the end of the .bss output section _ 


Address of the end of a function 


etext 


Several of these symbols appear in pairs: 


2 .bb/.eb indicate the beginning and end of a block. 
@ .of/.ef indicate the beginning and end of a function. 


@ nfake/.eos name and define the limits of structures, unions, and enu- 
merations that were not named. The .eos symbol is also paired with 
named structures, unions, and enumerations. 
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When a structure, union, or enumeration has no tag name, the compiler as- 
signs it a name so that it can be entered into the symbol table. These names 
are of the form .nfake, where rn is an integer. The compiler begins numbering 
these symbol! names at 0. 


A.7.1.171 Symbols and Blocks 


In C, a block is a compound statement that begins and ends with braces and 
contains symbol definitions. The symbol definitions for any particular block 
are grouped together in the symbol table, and are delineated by the .bb/.eb 
special symbols. Note that blocks can be nested in C, and their symbol table 
entries can also be nested correspondingly. Figure A-7 shows how block 
symbols are grouped in the symbol table. 


Symbol! Table 


Block1: | -bb_ 
Symbols for | 
block 1 
Block 2: 


Symbols for 
block 2 


Figure A-7. Symbols for Blocks 


A.7.1.2. Symbols and Functions 


The symbol definitions for a function appear in the symbol table as a group, 
delineated by .bf/.ef special symbols. The symbol table entry for the function 
name precedes the .bf special symbol. Figure A-8 shows the format of symbol 
table entries for a function. 


Symbols for 
the function 


Figure A-8. Symbols for Functions 


If a function returns a structure or union, then a symbol table entry for the 
special symbol .target will appear between the entries for the function name 
and the .bf special symbol. 
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A.7.2 Symbol Names 


The first 8 bytes of a symbol table entry (bytes 0-7) indicate a symbol’s name: 


@ If the symbol name is 8 characters or less, then this field has type char- 
acter. The name ts padded with nulls (if necessary) and stored in bytes 
0-7. 

@ If the symbol name is greater than 8 characters, then this field is treated 


as two long integers. The entire symbol name is stored in the string ta- 
ble. Bytes 0-3 contain 0, and bytes 4-7 are an offset into the string ta- 
ble. 


A.7.3 String Table 


Symbol names that are longer than eight characters are stored in the string 
table. The field in the symbol table entry that would normally contain the 
symbol’s name instead contains a pointer to the symbol’s name in the string 
table. Names are stored contiguously in the string table, delimited by a null 
byte. The first four bytes of the string table contain the size of the string table 
in bytes; thus, offsets into the string table are greater than or equal to four. 


Figure A-5 shows an example of a string table that contains two symbol 
names, Adaptive—Filter and Fourier—Transform. The index in the string table 
is 4 for Adaptive—Filter and 20 for the Fourier—Transform. 


Figure A-9. Sample String Table 
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A.7.4 Storage Classes 


Byte 16 of the symbol table entry indicates the storage class of the symbol. 
Storage classes refer to the method in which the C compiler accesses a sym- 
bol. Table A-11 lists valid storage classes. 


Table A-11. Symbol Storage Classes 


| Mnemonic |Value| Storage Class__ || Mnemonic |Value| Storage Class 
PC-NULL_ | 0 | Nostorage class {| C-UNTAG | 12 | Uniontag 
.c-AuTO |__| Automatic variable |] C-TPDEF | 13 | Type definition 
| External symbol || C-USTATIC__| 14 | Uninitialized static 
| Static I C-ENTAG | 15 | Enumerationtag 


ation 


External definition {| C_REGPARM 


block; used only for the 
.bb and .eb_- special 
symbols 
Member of a structure |} C—FCN 101 Beginning or end of a 
symbols 
C_ARG Function argument C_EOS 102 | End of structure; used 
only for the .eos special 
| symbol 
| C_STRTAG 10 | Structure tag C_FILE 103 | Filename; used only for | 
| the .file special symbol 
C_MOU 11 Member of a union CLINE 104 | Used only by utility 
| programs 


ptabel | CFIELD | 18 | Bit field 
function; used only for 
Some special symbols are restricted to certain storage classes. Table A-12 


)C-EXT | 2 
}C-STAT | 3 
C_ULABEL Undefined label C_BLOCK Beginning or end of a 
aa a the .bf and .ef special 
lists these symbols and their storage classes. 


Table A-12. Special Symbols and Their Storage Classes 


mentee to 
Symbol Storage Class 
| bb | =C-BLOCK | 
pcb | C-BLOCK_| 
| eos | CEOS 
| text | =C-STAT 
| bss | =C-STAT 
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A.7.5 Symbol Values 


Bytes 8-11 of a symbol table entry indicate a symbol’s value. A symbol’s va- 
lue depends on the symbol’s storage class; Table A-13 summarizes the stor- 
age classes and related values. 


Table A-13. Symbol Values and Storage Classes 


| Storage Class | Value Description 
|} C_AUTO Stack offset in bits 
| C_EXT . Relocatable address 


C_STAT Relocatable address | 
| C_REG | 
| C—LABEL 
C_MOS 
C_ARG 
C_STRTAG 


Register number 
Relocatable address 
Offset in bits 

Stack offset ‘n bits 
C_MOU 


Offset in bits | 
cuntas fo 
Peateper [0 


| C_ENTAG 
[cMoE | Enumeration value 
Terie fo ———is 


If a symbol’s storage class is C_FILE, then the symbol’s value is a pointer to 
the next .file symbol. Thus, the .file symbols form a one-way linked list in the 
symbol table. When there are no more .file symbols, the final .file symbol 
points back to the first .file symbol in the symbol table. 


The value of a relocatable symbol is its virtual address. When the linker relo- 
cates a section, the value of a relocatable symbol changes accordingly. 
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A.7.6 Section Number 


Bytes 12-13 of a symbol table entry contain a number that indicates which 


section the symbol was defined in. Table A-14 lists these numbers and the 
sections they indicate. 


Table A-14. Section Numbers 


Number Description 
| -2__| Special symbolic debugging symbol __| 
TN-ABS | -1 | Absolute symbol 
PN-UNDEF [0 | Undefined external symbol__— 
NOSCNUM |__1 | atextecction 
a ae 
eee ae! 


N—SCNUM .data section 
N—SCNUM .bss section 


N—SCNUM 4-65,535 | Section number of a named section, in 
the order in which the named sections 
are encountered 


Note that if there were no .text, .data, or .bss sections, the numbering of 
named sections would begin with 1. 


If a symbo! has a section number of 0, -1, or -2, then it is not defined in a 
section. A section number of -2 indicates a symbolic debugging symbol, 
which includes structure, union, and enumeration tag names, type definitions, 
and filenames. A section number of -1 indicates that the symbol has a value 
but is not relocatable. A section number of O indicates a relocatable external 
symbol that is not defined in the current file. 


A.7.7 Type Entry 


Bytes 14-15 of the symbol table entry define the symbol’s type. Each symbol! 
symbol has: 


@ One basic type 
© One to six derived types 


The format for this 16-bit type entry is: 


| Derived | Derived | Derived | Derived | Derived ae 
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Bits 0-3 of the type field indicate the basic type. Table A-15 lists valid basic 
types. 


Table A-15. Basic Types 


[Mnemonic [Value] Type 
2 [Character 
3 [Short imager 


ao. 
ae 

pe 

so 

ef 7 
[e| Structure 
[3 [union 
[11 | Member of an enumeration 
i 
= 


Unsigned integer 


Unsigned long integer | 


Bits 4-15 of the type field are arranged as six 2-bit fields which can indicate 
1 to 6 derived types. Table A-16 lists the possible derived types. 


Table A-16. Derived Types 


[Mnemonic [Value| Type 
DT-NON | 0 | Noderived ype | 
prprR | 1 [Pointer 


An example of a symbol! with several derived types would be a symbol with a 
type entry of 00000000110100115. This entry indicates that the symbol is a 
pointer to an array of short integers. 
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A.7.8 Auxiliary Entries 


Each symbol table may have one or no auxiliary entry. An auxiliary symbol 
table entry contains the same number of bytes as a symbol table entry (18), 
but the format of an auxiliary entry depends on the symbol’s type and storage 
class. Table A-17 summarizes these relationships. 


Table A-17. Auxiliary Symbol Table Entries Format 


Storage ; zy pe For - Auxiliary 
Class Derived Basic Entry Format 
Type 1 Type 
T 


C_FILE DT—NON T—NULL Filename (see Table A-18) 
C_STAT DT—NON T—NULL Section (see Table A-19) 


tagname C_STRTAG | DT—NON T—NULL Tag name (see Table A-20) 
C—_UNTAG 
C_ENTAG 


|.eos ————s«| C_EOS DT_NON T—NULL End of structure (see Table A-21) 


fcname | C_EXT DT—FCN (See note 1) | Function (see Table A-22) 
C_STAT 


(See note 2) | DT—ARY - (See note 1) | Array (see Table A-23) 
.bb, .eb C_BLOCK DT—NON T—NULL Beginning and end of a block 
(see Table A-24 and Table A-25) 
bf, .ef C_FCN DT—NON T—NULL Beginning and end of a function 
(see Table A-24 and Table A-25) 
Name related to a | (See note 2) | DT—PTR T STRUCT Name related to a structure, union, 
structure, union DT—ARR T—UNION or enumeration (see Table A-26) 
or enumeration DT—NON T_ENUM 


Notes: 1) Any except T-MOE | | 
2) C_AUTO, C—STAT, C_MOS, C—MOU, C—TPDEF 


In Table A-17, tagname refers to any symbol name (including the special 
symbol .nfake). fename and arrname refer to any symbol name. 


Any symbol that satisfies more than one condition in Table A-17 should have 
a union format in its auxiliary entry. Any symbol that does not satisfy any of 
these conditions should not have an auxiliary entry. 

A.7.8.1 File Names 


Each of the auxiliary table entries for a filename contains a 14-character file 
name in bytes 0-13. Bytes 14-17 are not used. 


Table A-18. Section Format for Auxiliary Table Entries 


Byte | 


417 [Noted 
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A.7.8.2 Sections 
The auxiliary table entries for sections have the format shown in Table A-18. 


Table A-19. Section Format for Auxiliary Table Entries 


Section length 
Unsigned short integer Number of relocation entries 


Unsigned short integer Number of line number entries 
a a Not used (zero filled) 


A.7.8.3 Tag Names 
Table A-20 illustrates the format of auxiliary table entries for tag names. 


Table A-20. Tag Name Format for Auxiliary Table Entries 


[umber] Tyee |Description 
o-7 | Unsigned shom integer —| Size of structure, union, or enumeration —| 
Pat Nor used Gero filed) J 


| 12-15 | Long integer Index of next entry beyond this structure, | 
| | union, or enumeration 


16-17 Not used (zero filled) | 2 


A.7.8.4 End of Structure 


Table A-21 illustrates the rormat of auxiliary table entries for ends of struc- 
tures. 


Table A-21. End of Structure Format for Auxiliary Table Entries 


| Seek Type Description 
Be eGR Bee 


| Not used (zero filled) 


Appendix A - Symbol Table 


A.7.8.5 Functions 
Table A-22 illustrates the format of auxiliary table entries for functions. 
Table A-22. Function Format for Auxiliary Table Entries 


3 
| 4-7 | ~~ Longinteger__—|_Size of function (in bits) 


12-15 | ———sLonginteger ==—s«|¥_—stndex of next entry beyond this function __| 


File pointer to line number | 
| PC: CNNot seed (zero filled) 


A.7.8.6 Arrays 
Table A-23 illustrates the format of auxiliary table entries for arrays. 
Table A-23. Array Format for Auxiliary Table Entries 


A.7.8.7 End of Blocks and Functions 


Table A-24 illustrates the format of auxiliary table entries for the ends of 
blocks and functions. 


Table A-24. End of Blocks and Functions Format for Auxiliary 
Table Entries 


fuurnber| Tye | escription 
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A.7.8.8 Beginning of Blocks and Functions 


Table A-25 illustrates the format of auxiliary table entries for the beginnings 
of blocks and functions. 


Table A-25. Beginning of Blocks and Functions Format for 


Auxiliary Table Entries 
Byte 
Number 


o-3 [| Noted (zero filled) 
| 6-11 Noted (zero filled) 
po Noted (zero filled) 


A.7.8.9 Names Related to Structures, Unions, and Enumerations 
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Table A-26 illustrates the format of auxiliary table entries for the names of 
structures, unions, and enumerations. 


Table A-26. Structure, Union, and Enumeration Names Format for 
Auxiliary Table Entries 


P03 [Long integer Tag index 
eC 
“7 [Unsigned show integer | Size ofthe structure, union, or enumaraion | 
Pea [Not used Gee filed) 
[Fu Gar fled) 


Appendix B 
Symbolic Debugging Directives 


The TMS320C30 assembler supports several directives that the TMS320C30 
C compiler uses for symbolic debugging: 


The .sym directive defines a global variable, a local variable, or a func- 
tion. Several parameters allow you to associate various debugging in- 
formation with the symbol or function. 


The .stag, .etag, and .utag directives define structures, enumerations, 
and unions, respectively. The .member directive specifies a member 
of a structure, enumeration, or union. The .eos directive ends a struc- 
ture, enumeration, or union definition. 

The .func and .endfunc directives specify the bounds of C blocks. 


The .file directive defines a symbol in the symbol table that identifies 
the current source file name. 


The .line directive identifies the line number of a C source statement. 


These symbolic debugging directives are not usually listed in the assembly 
language file that the compiler creates. If you want them to be listed, invoke 
the code generator with the -o option, as shown below: 


cg30 -o <input file> 


This appendix contains an alphabetical directory of the symbolic debugging 
directives. Each directive contains an example of C source and the resulting 
assembly language code. 


.block/.endblock Define a Block 


Syntax 


Description 


Example 
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«block beginning line number 
-.endblock ending line number 
The .block and .endblock directives specify the beginning and end of aC 


block. The line numbers are optional; they specify the location in the 
source file where the block is defined. 


Note that block definitions can be nested. The assembler will detect im- 
proper block nesting. 


Here is an example of C source that defines a block, and the resulting as- 
sembly language code. 


C source: 
{ /* Beginning of a block */ 
int. a,b} 
a= b; 
3 /* End of a block * / 


Resulting assembly language code: 


- block 0 

.sym ee 
-sym =b,2,4,2,32 
line 7 

LDI *+FP(2),RO 

STI RO, *+FP(1) 
-endblock 7 


Supply a File Identifier file 


Syntax file “filename” 


Description _ The .file directive allows a debugger to map locations in memory back to 
lines in a C source file. filename is the name of the file that contains the 
orginal C source program. The first 14 characters of the filename are sig- 
nificant. 


You can also use the .file directive in assembly code to provide a name in 
the file and improve program readability. 


Example Here’s an example of the .file directive. The file name named text.c con- 
tained the C source that produced this directive. 
-file "text.c" 
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func/.endfunc Define a Function 


Syntax 


Description 


Example 
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func beginning line number 

.endfunc§ ending /ine number 

The .func and .endfunc directives specify the beginning and end of a C 
function. The line numbers are optional; they specify the location in the 
source file where the function is defined. 


Note that function definitions cannot be nested. 


Here is an example of C source that defines a function, and the resulting 
assembly language code. 


C source: 
power(x, n) /* Beginning of a function */ 
tnt. <1; 
{ 

ant <i, ps 

= Ls 
for (i = 1; i <= n; ++1) 
Dp °F 2; 
return p; /* End of function of 


Define a Function func/.endfunc 


Resulting assembly language code: 


0007 -sym —power ,—power,36,2,0 
0008 -global —power 

0009 

0010 .func 2 

OO1L1 KKEEKKRKEKEKEKEKEKEKKEKRKRKCKEKREKRKEKEKKEKKEKRKEKEKRKKRKAEESK 
0012 * FUNCTION DEF —power 
0013 KKEKKKKKEKKKEKEKEKEKEKKRKEKKKEKEKKKKRKEKRKKKKKRKEEEK 
0014 O00000 —power: 

0015 OO00000 OF2BO000 PUSH FP 

0016 O00001 O80B0014 LDI SP,FP 

0017 000002 02740001 ADDI 1,SP 

0018 000003 OF240000 PUSH R4 

0019 .sym —x,—2,4,9,32 
0020 .sym BR 6 Wires re Bee ee 
0021 .sym ft py ee pe 
0022 -sym —p,4,4,4,32 
0023 000004 .- line 5 

0024 000004 08640001 LDI 1,R4 

0025 OOO0005 . line 6 

0026 OO0O005 15440301 STI R4,*+FP(1) 
0027 OO0006 3% 

0028 OO00006 08400301 LDI *+FP(1),RO 
0029 O00007 O4CO0OBO3 CMPI *+FP(3),RO 
0030 000008 6A090008 BGT L2 

0031 000009 . line 7 

0032 O00009 O8000004 LE R4,RO0 

0033 OOOOOA 08410B02 LDI *-FP(2),R1 
0034 OOOOO0OB 62000000! CALL I_~MULT 

0035 OOOO0O0C 08040000 LDI RO,R4 

0036 OOOOOD 08410301 LDI *+FP(1),R1 
0037 OQOOQOOE 02610001 ADDI 1,R1 

0038 OOOOOF 15410301 STI R1L,*+FP(1) 
0039 000010 60000006+ BR L3 

0040 OO00011 Las 

0041 000011 . line 8 

0042 000011 O8000004 LDI R4,RO 

0043 000012 EPIOW—1: 

0044 000012 OE240000 POP R4 

0045 000013 18740001 SUBI 1,SP 

0046 000014 OE2BO0000 POP FP 

0047 000015 78880000 RETS 

0048 

0049 .endfunc ll 
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.line 


Create a Line Number Entry 


Syntax 


Description 


Example 
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line /ine number[,address/] 


The .line directive creates a line number entry in the object file. Line num- 
ber entries are used in symbolic debugging to associate addresses in the 
object code with the lines in the source code that generated them. 


The .line directive has two operands: 


® Line number indicates the line of the C source that generated a por- 
tion of code. Line numbers are relative to the beginning of the current 
function. This is a required parameter. 


® Address is an expression which is the address associated with the line 
number. This is an optional parameter; if you don’t specify an ad- 
dress, the assembler will use the current SPC value. 


The .line directive is followed by the assembly language source statements 
that are generated by the indicated line of C source. For example, assume 
that the lines of C source below are line 4 and 5 in the original C source; 
lines 5 and 6 produce the assembly language source statements that are 
shown below. | 


C source: 
for (1 = 1; i <= n; +41) 

p=p* xX; 
Resulting assembly language code: 
0023 000004 .Lline 5 
0024 OO00004 08640001 EDT 1,R4 
0025 OO0005 . line 6 
0026 OO0O0005 15440301 STL R4,*+FP(1) 
0027 OO0006 L3: 
0028 OO00006 08400301 LDI *+FP(1),RO 
0029 O00007 O4CO0BO3 CMPI *+FP(3),RO 
0030 OO00008 6A090008 BGT L2 
0031 000009 . line 7 
0032 000009 O8000004 LDI R4,RO 
0033 OOQOOA 08410B02 LDI *-FP(2),R1 
0034 OOOO0O0B 62000000! CALL I_-MULT 
0035 O0000C 08040000 LDI RO,R4 
0036 OOO0O0O0OD 08410301 LDI *+FP(1),R1 
0037 OOOOOE 02610001 ADDI LL, Rd 
0038 OOOOOF 15410301 STI R1,*+FP(1) 
0039 000010 60000006+ BR L3 


Define a Member .member 


Syntax 


Description 


Example 


-member name,va/lue/,type,storage class,size,tag,dims / 


The .member directive defines a member of a structure, union, or enumer- 
ation. It is only valid when it appears in a structure, union, or enumeration 


definition. 

@ Name is the name of the member that is put in the symbol table. The 
first 32 characters of the name are significant. 

@ Value is the value associated with the member. Any legal expression 
(absolute or relocatable) is acceptable. 

Ys Type is the C type of the member. Appendix A contains more infor- 
mation about C types. 

e Storage class is the C storage class of the member. Appendix A 
contains more information about C storage classes. 
Size is the number of bits of memory required to contain this member. 
Tag is the name of the type (if any) or structure of which this member 
is a type. This name must have been previously declared by a .stag, 
.etag, or .utag directive. 

@ Dims may be one to four expressions separated by commas. This al- 


lows up to four dimensions to be specified for the member. 


The order of parameters is significant. Mame and va/ue are required pa- 
rameters. All other parameters may be omitted or empty (adjacent commas 
indicate an empty entry). This allows you to skip a parameter and specify 
a parameter that occurs later in the list. Operands that are omitted or empty 
assume a null value. 


Here is an example of a C structure definition and the corresponding as- 
sembly language statements: 


C source: 


struct doc { 


char title; 
char group; 
int job—number; 


} doc_info; 


Resulting assembly language code: 


.stag doc,48 

-member —title,0,2,8,4% 
-member —group, 8,2,8,8 
-member —job—number,16,4,8,32 
-e0s 
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.stag/.etag/.utag/.eos Define a Structure 


Syntax Stag namef[,size] 
member definitions 
.eos 


.etag name[,size] 
member definitions 
.eos 


.utag name/,size] 
member definitions 
.eos 


Description The .stag directive begins a structure definition. The .etag directive begins 
| an enumeration definition. The .utag directive begins a union definition. 
The .eos directive ends a structure, enumeration, or union definition. 


@ Name is the name of the structure, enumeration, or union. The first 
32 characters of the name are significant. This is a required parame- 
ter. 


@ Size is the number of bits the structure, enumeration, or union occu- 
pies in memory. This is an optional parameter; if omitted, the size is 
unspecified. 


The .stag, .etag, or.utag directive should be followed by a number of 
.member directives, which define members in the structure. The .member 
directive is the only directive that can appear inside a structure, enumer- 
ation, or union definition. 


The assembler does not allow nested structures, enumerations, or unions. 
The C compiler “unwinds” nested structures by defining them separately 
and then referencing them from the structure they are referenced in. 


Example 7 Here is an example of a structure definition. 
C source: 
reece doc 
char title; 
char group; 
tnt jyob_number ; 


} doc—info; 


Resulting assembly language code: 


.stag —doc,96 

-member —title,0,2,8,32 
-member —group,32,2,8,32 
-member —job-—number,64,4,8,32 
-eos 
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Define a Structure 


Example 2 


Example 3 


Here is an example of a union definition. 


C source: 


union u—tag { 
int vall; 
float val2; 
char valc; 
3} valu; 


Resulting assembly language code: 


-utag —u—tag,96 
-member —~vall1,0,2,8,32 
-member ~val2,32,4,8,32 
-member ~valc,64,4,8,32 
.eos 


Here is an example of an enumeration:-definition. 


C Source: 


{ | 
enum o_ty { reg_l, reg—2, result } optypes; 


Resulting assembly language code: 


-etag ~O-cy; 32 

-member —reg—1,0,11,16,32 

-member ~reg—2,1,11,16,32 

-member —~result,2,11,16,32 
-e@os 


.Stag/.etag/.utag/.eos 
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sym 


Syntax 


Description 


Example 


Define a Symbol 


sym name,value[,type,storage class,size,tag,dims] 


The .sym directive specifies symbolic debug information about a global 
variable, local variable, or a function. 


Name is the name of the variable that is put in the object symbol ta- 
ble. The first 32 characters of the name are significant. 


Va/ue is the value associated with the variable. Any legal expression 
(absolute or relocatable) is acceptable. 


Type is the C type of the variable. Appendix A contains more infor- 
mation about C types. 


Storage class is the C storage class of the variable. Appendix A con- 
tains more information about C storage classes. 


Size is the number of words of memory required to contain this vari- 
able. 


Tag is the name of the type (if any) or structure of which this variable 
is a type. This name must have been previously declared by a .stag, 
.etag, or .utag directive. 


Dims may be up to four expressions separated by commas. This al- 
lows up to four dimensions to be specified for the variable. 


The order of parameters is significant. Name and va/ue are required pa- 
rameters. All other parameters may be omitted or empty (adjacent commas 
indicate an empty entry). This allows you to skip a parameter and specify 
a parameter that occurs later in the list. Operands that are omitted or empty 
assume a null value. 


These lines of C source produce the .sym directives shown below: 


C source: 


Struct s { int memberl, member2; 3} str; 
int ext; 
int array[5][10]; 


long 


*DCX 3 


int stremp(); 


main(argl,arg2) 


int argl; 
char *arg2; 


register rl; 


Resulting assembly language code: 


.sym —SUCY, Str, 3, 2; 64;—8 

-sym =OxXxt,.ext,4,2;52 

-sym —array,—array,244,2,1600,,5,10 
-sym —{ptr,—_ptr,21,2,32 

.sym —main,—main, 36,2,0 

.sym —~argl,—argl, -2,4,9,32 

-sym —arg2,—arg2,-3,18,9,32 


.sym —r1,4,4,4,32 
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Assembler Error Messages 


The assembler issues several types of error messages: 


e Fatal, 

@ Nonfatal, and 

e Macro errors. 

When the assembler completes it second pass, it reports on any errors that it 
encountered during the assembly. It also prints these errors in the listing file 
(if one is created); an error is printed following the source line that incurred 
it. 

This section discusses the three types of assembler error messages; they are 


listed in alphabetical order. Most errors are fatal errors; if an error is not fatal 
or if it is a macro error, this is noted in the list. 


absolute value required: A relocatable symbol was used where an absolute 
symbol was expected. 


address required: This instruction requires an address as an operand. 


auxiliary register required for indirect: This instruction requires an 
auxiliary register aS an operand. 


blank missing: A blank or blanks must separate each field of the source 
statement. 


cannot open library: A library name specified with the .mlib directive does 
not exist or is already being used. 


closing (’)') missing: Mismatched parenthesis. 
closing quote missing: Alli strings must be enclosed in quotes. 


comma missing: The assembler expected a comma but did not find one. 
This usually means that more operands were expected. 


copy file open error: A file specified by a .copy directive does not exist or 
is already being used. 


divide by zero: An expression or well-defined expression contains invalid 
division. 
duplicate definition: The symbol appears as an operand of a REF state- 


ment, as weil as in the the label fieid of the source, or, the symbol appears 
more than once in the label field of the source. 


.eise needs corresponding .if: An .else directive was not preceded by a |! 
directive. 


SEND statement missing in macro (macro error message 2): Within the 
macro library, an end of Tile was encountered before a SEN card. 
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expression out of bounds: 


expression syntax error: Unbalanced parentheses or invalid operations on 
relocatable symbols. 


extended register required: This instruction requires an extended register 
(RO-R7) as an operand. 


filename missing: The specified filename cannot be found. 


floating-point number not valid in expression: Floating-point numbers 
cannot be used in expressions; you must use an integer instead. 


SIF level exceeded (macro error message): The maximum nesting level of 
SIF directives is 44. 


illegal label: A label cannot be used for the second instruction of a parallel 
instruction pair. 


illegal structure, union, or enumeration tag 
illegal structure definition 


include/copy files not allowed in macro: You can’t use the .copy di- 
rective within a macro. 


incompatible addressing modes: An invalid combination of addressing 
modes has been used in an instruction. 


incorrect macro definition (macro error message): Within the macro li- 
brary, a macro was not found or a macro name was not given for a macro call. 


index register required for displacement: Use an index register for in- 
direct addressing. 


indirect address required: This instruction expects an indirect address as 
an operand. 


indirect displacement must be 0 or 1: The indirect placement for parallel 
instructions or three-operand instructions must be 0 or 1. 


indirect displacement or out of bounds: The displacement for this in- 
struction must be in the range 0-255. 


invalid branch displacement: The specified displacement is a absolute but 
the SPC is relative, or the displacement is an external value, or the relative 
displacement is too large. 


invalid bit-reversed modification 
invalid circular modification 


invalid expression: This may indicate invalid use of a relocatable symbol in 
arithmetic. 


invalid floating-point constant: 


invalid $IF structure (macro error message): The macro does not have 
matching SIF, SELSE, and SENDIF statements. 


invalid SIF/SLOOP nesting (macro error message): An SIF used within a 
$LOOP must end within the SLOOP; a SLOOP within an SIF must end within 
the SIF. 
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invalid macro expansion (macro error message) 


invalid macro library pathname (macro error message): The macro library 
name that was specified with an .mlib directive is invalid. 


invalid macro qualifier (macro error message): The only valid macro qua- 
lifiers are S, V, L, A, SS, SV, SL, and SA. 


invalid macro verb (macro error message) 


invalid opcode: The command field of the source record has an entry that 
is not a defined instruction, directive, or macro name. 


invalid option: An option specified by the .option directive is invalid. 


invalid parallel instruction combination: The instructions specified as 
parallel instructions are not a valid pair. 


invalid symbol: The symbol has invalid characters in it. 
invalid symbol in macro expansion (macro error message) 
invalid use of .asect 

label required: The flagged directive must have a label. 


long macro variable qualifier (macro error message): Macro variable 
qualifiers may be only one or two characters long. 


library not archive: A file specified with an .mlib directive is not an archive 
file. 


loop nesting level exceeded (macro error message) 


macro line too long (macro error message): In a macro definition, macro 
directive lines may be only 53 characters long. Model statements, when fully 
expanded, may be only 55 characters long. 


macro nesting level exceeded (macro error message) 


missing first half of parallel instruction: The first instruction in a parallel 
instruction pair is missing or invalid. 


operand missing: An operand must be supplied. 


operand must be register or indirect: Three-operand and parallel in- 
structions require register or indirect operands. 


overflow in floating-point constant: Floating-point value to large to be 
represented. 


pass1/pass2 operand conflict: A symbol in the symbol table did not have 
the same value in pass 1 and pass 2. 


positive value required 


RO or R1 multiply destination required: The destination operand for an 
MPY||ADD pair or an MPY||SUB pair must be RO or R71. 


R2 or R3 ADD/SUB destination required: The destination operand for 
parallel ADD or SUB instructions must be R2 or R3. 


register required: This instruction requires a register as an operand. 
relocatable field must be 32 bits 
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string required: You must supply a string that is enclosed in double quotes. 
symbol required: The .global directive requires a symbol as an operand. 
symbol used in both REF and DEF: A REF symbol is already defined. 
syntax error: 

syntax error in macro assignment (macro error message) 

syntax error in macro expansion (macro error message) 


too many macro variables (macro error message): The total number of 
macro parameters, variables and labeis in a single macro definition may not 
exceed 128. 


unbalanced symbol table entries: For .block and .func directives. 


undefined symbol: An undefined symbol was used where a well-defined 
expression is required. 


underflow in floating-point constant: Floating-point value is too small 
to represent. 


unexpected .endif encountered: An .endif directive was not preceded by 
an .if directive. 


variable already defined (macro error message): A macro variable cannot 
be redefined within a macro. 


warning — illegal relative branch: A branch has been requested to a dif- 
ferent section. 


warning - immediate operand not absolute 


warning — null string defined: An empty string (one whose length = 0) 


is defined for string input, for directives that require a null string operand. 


warning — register converted to immediate 


warning - same destination registers: Parallel instructions must use 
different destination registers. 


warning - symbol truncated: The maximum length for a symbol is eight 
characters. The assembler ignores the extra characters. 


warning - trailing operand(s): The assembler found fewer or more oper- 
ands than expected in the flagged instruction. 


warning — value out of range 


warning - value truncated: The expression given was to large to fit within 
the instruction opcode or the required number of bits. 
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Linker Error Messages 


The linker issues several types of error messages: 


Syntax and command errors 
Allocation errors 
1/O errors 


This section discusses the three types of errors; they are listed alphabetically 
within each category. The symbol:"(...)” is used in these listings to represent 
the name of an object that the linker is attempting to interact with when an 
error occurs. 


Syntax/Command Errors 


These errors are caused by incorrect use of linker directives, misuse of 
an input expression, invalid options, Check the syntax of all expressions, 
check the input directives for accuracy. Review the various options you | 
are using and check for conflicts. 


absolute symbol (...) being redefined: An absolute symbol may 
not be redefined. 


adding name (...) to multiple output sections: The input section 
is mentioned twice in the SECTION directive. 


ALIGN illegal in this context: Alignment of a symbol may only be 
performed within a SECTIONS directive. 


attempt to decrement 


bad attribute value in MEMORY directive: (...): An attribute 
must be R, W, X, or I. 


bad flag value in SECTIONS directive, option (...) 
bad fiil value: The fill value must be a 2-byte constant. 


binding excludes alignment: The section will be bound at the spe- 
cified address regardless of the alignment of that address. 


both -r and -s flags are set; -s flag turned off: Since the -s op- 
tion strips the relocation information and -r requests a relocatable object 
file, these options are in conflict with each other. 


-c requires fill value of 0 in .cinit: The value parameter has been 
overridden. 


-f flag does not specify a 2-byte number 
cannot align a section within GROUP - (...) not aligned 


cannot bind a section within a GROUP 


Appendix D - Linker Error Messages 


D-2 


cannot specify an owner for sections within a GROUP: The 
entire group is treated as one unit, so the group may be aligned: or 
bound to an address, but the sections making up the group may not be 
handled individually. 


cannot specify a page for a section within a GROUP 


DSECT (...) can’t be given an owner: Since dummy sections do 
not participate in memory allocation, it is meaningless for a dummy 
section to be given an owner or an attribute. 


DSECT (...) can’t be linked to an attribute 

-e flag does not specify a legal symbol name (...) 

entry point other than —c—int00 specified: For -c option only. 
entry point symbol (...) undefined 

errors in input — (...) not built 

fill value on -f flag truncated to (...) bytes (warning) 


ifile (comfile) nesting exceeded with file (...): Command file 
nesting is allowed up to 16 levels. 


illegal operator in expression 


misuse of ”.” symbol in assignment instruction: The dot symbol 
cannot be used in assignment statements that are outside SECTIONS 
directives. 


no input files 

number (...) not a power of 2: For the ALIGN operator. 

-o file name too large (>128 char), truncated to (string) 
-o flag does specify a valid file name : string 

option flag does not specify a number 

option is invalid flag 


section (...) not built: The most likely cause of this is a syntax error 
in the SECTIONS directive. 


semicolon required after expression 
statement ignored: Caused by a syntax error in a expression. 
symbol referencing errors -— (...) not built 


symbol (...) from file (...) being redefined: A defined symbol may 
not be redefined in an assignment statement. 


syntax error: scanned line = (...) 


unexpected EOF(end of file): Syntax error in the linker command 
file. 


undefined symbol in expression 
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e Allocation Errors 


These error messages appear during the allocation phase of linking. 
They generally appear if a section or group does not fit at a certain ad- 
dress or if the MEMORY and SECTION directives conflict in some way. 
If you are using a linker command file, check that MEMORY and SEC- 
TION directives allow enough room to ensure that no sections overlap 
and that no sections are being placed in unconfigured memory. 


binding address (...) for section (...) is outside all memory on 
page (...) 


binding address (...) for section (...) overlays previously allo- 
cated section 


binding address (...) incompatible with alignment for section 


can’t allocate output section, (...) of size (...) on page (...) 
can’t allocate section (...) with attribute (...) on page (...) 
default allocation failed: (...) is too large 

GROUP containing section (...) is too big 

internal symbol (...) redefined in file (...): Ignored. 
memory types (...) and (...) on Page (...) overlap 


no owner (...) for section (...) on page (...): Invalid or nonexistent 
memory range. 


output file (...) not executable Warning. 
PC-relative displacement overflow at address (...) in file (...) 


section (...) at address (...) overlays previously allocated sec- 
tion (...) at address 


section (...), bound at address (...), won’t fit into page (...) of 
configured memory 


section (...) enters unconfigured memory at address (...) 
section (...) in file (...) is too big 


undefined symbol (...) first referenced in file (...): Unless the 
-r option is used, the linker requires that all referenced symbols are de- 
fined. 


e 1/O Errors: 


The foilowing error messages indicate that the input file is corrupt, no- 

nexistent, or unreadable or because the linker cannot write to the output 

file. Make sure that the input file is in the correct directory and that the 

vs system is not out of space. If the input file is corrupt, try reassem- 
ing It. 


cannot complete output file (...), write error 


cannot create output file (...): 
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can’t open (...) 

can’t read (...) 

can’t seek (...) 

could not create map file (...) 

fail to copy (...) 

fail to read (...) 

fail to seek (...) 

fail to skip (...) 

fail to write (...) 

file (...) has no relocation information 

file (...) is of unknown type, magic number = (...) 

illegal relocation type (...) found in section(s) of file (...) 
internal error : aux table overflow 

invalid archive size for file (...) 

1/O error on output file (...) 

library (...) member has no relocation information 

line number entry found for absolute symbol 

memory allocation failure 

no symbol map produced - not enough memory 
relocation symbol not found: index (...), section (...), file (...) 
relocation entries out of order in section (...) of file (...) 


section (...) not found: An input section specified in a SECTIONS 
directive was not found in the input file. 


sections .text, .data, or .bss not found: Optional! header may be 
useless. 


seek to (...) failed 
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absolute address: An address that is permanently assigned to a 
TMS320C30 memory location. 


absolute section: An initialized named section defined with the .asect di- 
rective. All addresses in an absolute section are absolute. 


alignment: A process in which the linker places an output section at an 
address that falls on an n-bit boundary, where n is a power of 2. You can 
specify alignment with the SECTIONS linker directive. 


allocation: A process in which the linker determines the final memory ad- 
dresses of output sections. 


archive library: A collection of individual files that have been grouped into 
a single file. 


archiver: A software program that allows you to collect several individual 
files into a single file called an archive library. The archiver also allows you 
to delete, extract, or replace members of the archive library, as well as add new 
members. 


assembler: A software program that creates a machine-language program 
from a source file that contains assembly language instructions, directives, and 
macro directives. The assembler substitutes absolute operation codes for 
symbolic operation codes, and absolute or relocatable addresses for symbolic 
addresses. 


assembly-time constant: A symbol that is assigned a constant value with 
the .set directive. 


assignment statement: A statement that assigns a value to a variable. 


attribute component: Provides information about the origin and structure 
of a macro variable or macro symbol. 


autoinitialization: The process of initializing global C variables (contained 
in the .cinit section) before beginning program execution. 


auxiliary entry: A symbol may have an extra entry in the symbol table that 
contains additional information about the symbol (whether the symbol ts a 
filename, a section name, a function name, etc.). 


binding: A process in which you specify a distinct address for an output 
section or a symbol. 


block: A set of declarations and statements that are grouped together with 
braces. 


-bss: This is one of the default COFF sections. You can use the .bss direc- 
tive to reserve a specified amount of space in the memory map that can later 
be used for storing data. The .bss section is uninitialized. 
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cache memory: A fast local memory onboard the TMS320C30. Blocks of 
code that are executed repeatedly can be loaded into the cache; this reduces 
the number of memory cycles and speeds program execution. 


C compiler: A program that translates C source statements into 
TMS320C30 assembly language source statements. 


command file: A file that contains linker options and names input files for 
the linker. 


comment: A source statement (or portion of a source statement) that is 
used to document or improve readability of a source file. Comment are not 
compiled, assembled, or linked; they have no effect on the object file. 


common object file format (COFF): An object file that promotes mod- 
ular programming by supporting the concept of sections. 


conditional processing: A method of processing one block of source 
code or an alternate block of source code, based upon the evaluation of a 
specified expression. 


configured memory: Memory that the linker has specified for allocation. 
constant: A numeric value that can be used as an operand. 


cross-reference listing: An output file created by the assembler that lists 
the symbols that were defined, what line they were defined on, which lines 
referenced them, and their final values. 


.data: This is one of the default COFF sections. The .data section is an ini- 
tialized section that contains usually initialized data. You can use the .data 
directive to assemble codge into the .data section. 


digital signal processon: A microprocessor/microcomputer that performs 
algorithmic or numerical computational procedures upon digitized signals it 
has received and then sendg the results to a host system or peripheral device. 


digital signals: Digital representation of a continuous signal. Usually am- 
plitude is represented at discrete time intervals with a digital value. 


directive: Special-purpose commands that control the actions and func- 
tions of a software tool (as opposed to assembly language instructions, which 
control the actions of a device). 


emulator: A hardware development system that emulates TMS320C30 
operation. | 


entry point: The starting execution point in target memory. 
enumeration: 


executable module: An object file that has been linked and can be exe- 
cuted in a TMS320C30 system. 


expression: A constant, a symbol, or a series of constants and symbols se- 
parated by arithmetic operators. 


external symbo!: A symbol that is used tn the current program module but 
defined in a different program module. 


field: For the TMS320C30, a software-configurable data type whose length 
can be programmed to be any value in the range of 1-32 bits. 
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file header: A portion of a COFF object file that contains general informa- 
tion about the object file (such as the number of section headers, the type of 
system the object file can be downloaded to, the number of symbols in the 
symbol table, and the symbol table’s starting address). 


global: Describes a symbol that is either 1) defined in the current module 
and accessed in another, or 2) accessed in the current module but defined in 
another. 


GROUP: An option of the SECTIONS directive that forces specified output 
sections to be allocated contiguously (as a group). 


high-level language debugging: The ability of a compiler to retain sym- 
bolic and high-level language information (such as type and function defi- 
nitions) so that a debugging tool can use this information. 


hole: An area between the input sections that comprise an output section 
which contains no actual code or data. 


incremental linking: Linking files that have already been linked. 


initialized section: A COFF section that contains executable code or ini- 
tialized data. These sections can be built up with the .data, .text, .sect, or 
.asect directives. 


input section: A section from an object file that will be linked into an ex- 
ecutable module. 


label: A symbol which begins in column 1 of a source statement and cor- 
responds to the address of that statement. 


length component: A component of a macro variable or macro symbol 
that contains the number of characters that make up the string. 


line number entry: An entry in a COFF output module that maps lines of 
assembly code back to the original C source file that created them. 


linker: A software tool that combines object files to form an object module 
that can be allocated into TMS320C30 system memory and executed by the 
TMS320C30. 


listing file: An output file created by the assembler that lists source state- 
ments, their line numbers, and their effects on the SPC. 


loader: A device that loads an executable module into TMS320C30 system 
memory or to a debugging tool. 


member: The elements or variables of a structure, union, or enumeration. 
macro: A user-defined routine that can be used as an instruction. 
macro call: The process of invoking a macro. 


macro definition: A block of source statements that define the name and 
the code that make up a macro. 


macro expansion: The source statements that are substituted for the macro 
call and subsequently assembled. 


macro library: An archive library composed of macros. Each file in the li- 
brary must contain one macro; it’s name must be the same as the macro name 
it defines, and it must have an extension of .asm. 
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macro variable: A variable that is valid within a macro definition or during 
a macro expansion. 


magic number: An entry in the COFF file header that identifies an object 
file as a module that can be executed by the TMS320C30. 


map file: An output file created by the linker that shows the memory con- 
figuration, section composition and allocation, and symbols and the addresses 
at which they were defined. 


memory map: A map of TMS320C30 target system memory space, which 
is partitioned into functional blocks. 


mnemonic: An instruction name that the assembler translates into machine 
code. 


model statement: Instructions or assembler directives in a macro defi- 
nition that are assembled each time a macro is invoked 


named section: A section that is defined with the .sect, .asect, or .usect 
directive. The .sect and .asect directives define initialized named sections that 
can be used like the .text and .data default sections. The .usect directive de- 
fines uninitialized named sections that can be\used like the .bss default sec- 
tion. 


object file: A file that has been assembled or linked and contains ma- 
chine-language object code. 


object format converter: A program that converts COFF object files into 
Intel-format or Tektronix-format object files. 


object library: An archive library made up of individual object files. 


operand: The arguments, or parameters, of an assembly language in- 
struction, assembler directive, or macro directive. 


optional header: A portion of ~. COFF object file that the linker uses to 
perform relocation at download time. . 


options: Command parameters that allow you to request additional or spe- 
cific functions when you invoke a software tool. 


output module: A linked, executable object file that can be downloaded 


and executed on a target system. 
output section: A final, allocated section in a linked, executable module. 


overlay pages: Multiple areas of physical memory that overlay each other 
at the same address. The TMS320C30 system can map different pages into 
the same address space in response to hardware select signals. 


partial linking: Linking a file that will be linked again. 


RAM model: An autoinitialization model used by the linker when linking 
C code. The linker uses this model when you invoke the linker with the -cr 
option. The RAM model allows variables to be initialized at load time instead 
of run time. 


raw data: Executable code or initialized data in an output section. 


relocation: A process in which the linker adjusts all the references to a 
symbol when the symbol’s address changes. 
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ROM model: An autoinitialization model used by the linker when linking 
C code. The linker uses this model when you invoke the linker with the -c 
option. In the ROM model, the linker loads the .cinit section of data tables 
into memory, and variables are initialized at run time. 


section: A relocatable block of code or data that will ultimately occupy 
contiguous space in the TMS320C30 memory map. 


section header: A portion of a COFF object file that contains information 
about a section in the file. Each section has its own header; the header points 
to the section’s starting address, contains the section’s size, etc. 


section program counter: See SPC. 
sign-extend: To fill the unused MSBs of a value with the value’s sign bit. 


simulator: A software development system that simulates TMS320C30 
operation. 


source file: A file that contains C code or TMS320C30 assembly language 
code that will compiled or assembled to form an object file. 


SPC: Section Program Counter. An element of the assembler that keeps 
track of the current location within a section; each section has its own SPC. 


static: Refers to a variable whose scope is confined to a function or a pro- 
gram. The values of static variables are not discarded when the function or 
program is exited; their previous value is resumed when the function or pro- 
gram is re-entered. 


storage class: Any entry in the symbol table that indicates how a symbol 
should be accessed. 


string component: A copy of a string that is passed to a macro variable 
by a macro parameter or assigned to a macro symbol with an $ASG directive. 


string table: Symbol names that are longer than 8 characters cannot be 
stored in the symbol table; instead, they are stored in the string table. The 
name portion of the symbol’s entry points to the location of the string in the 
string table. 


structure: A collection of one or more variables grouped together under a 
single name. 


symbol: A string of alphanumeric characters that represents an address or 
a value. 


symbolic debugging: The ability of a software tool to retain symbolic tn- 
forrnation so that it can be used by a debugging tool such as a simulator or 
an emulator. 


symbol table: A portion of a COFF object file that contains information 
about the symbols that are defined and used by the file. 


|” 


tag: An optional “type” name that can be assigned to a structure, union, or 


enumeration. 


target memory: Physical memory in a TMS320C30-based system into 
which executable object code will be loaded. 


text: This is one of the default COFF sections. The .text section is an ini- 
tialized section that contains executable code. You can use the .text directive 
to assemble code into the .text section. 
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unconfigured memory: Memory that is not defined as part of the 
TMS320C30 memory map and cannot be loaded with code or data. 


uninitialized section: A COFF section that reserves space in the 
TMS320C30 memory map but that has no actual contents. These sections 
are built up with the .bss and .usect directives. 


union: A variable which may hold (at different times) object of different 
types and sizes. 


unsigned: Refers to a value that is treated as a positive number, regardless 
of its actual sign. 


value component: A component of a macro variable or macro symbol that 
specifies the value of the variable or symbol. 


well-defined expression: An expression that contains only symbols or 
assembly-time constants that have been defined before they appear in the 
expression. 


word: A 32-bit addressable location in target memory. 
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overlay pages 9-24 
section specifications 9- 
syntax 9-16 
set (assembler directive) 
simulator 1-3 
software development system 
software installation 
list of supported operating 
systems 2-1 
PC-DOS 2-2 
VAX/VMS 2-3 
source listings 4-15-4-16 
source statement format 4-6 
comment field 4-7 
label field 4-6 
mnemonic field 4-7 
operand field 4-7 
optional syntaxes 6-3 


-41, 3-3, 


7, 5-22, 


3-2, 3-5, 5-15, 


3-10, 


17 


5-42, 5-6 


1-3 


2-1-2-3 


parallel instructions 6-18 


space (assembler directive) 
SPC 3-6, 4-15, 9-34 
assembler symbol 4-7 
linker symbol 9-33 
special section types 9-29 
special symbols in the symbol 


stag (assembler directive) B- 


static symbols 9-7 

static variables A-11 

storage classes A-15 

store instructions 6-21 
string (assembler directive) 
string table A-14 

stripping line number entries 
stripping symbolic information 


5-43, 5-6 


table A-12 
1,B-8 


5-44, 5-6 


9-10 
9-10 
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structure definitions A-20, B-8 
style and symbol conventions 1-7 
support tools 1-1, 1-2 
.sym (assembler directive) B-1, B-10 
symbol names A-14 
symbol table 3-17, A-11 
symbol] table entries B-10 
symbolic debugging 9-10, A-9, A-11, 
B-1-B-10 
assembler directives 5-1, B-1 
block definitions B-2 
enumeration definitions B-8 
file identification B-3 
function definitions B-4 
line number entries B-6 
member definitions B-7 
-s assembler option 4-3 
structure definitions B 
symbol table entries B-10 
union definitions B-8 
symbols 3-1/7, 4-11 
at link time 9-30 
character strings 4-11 
predefined 4-11 
relocatable symbols in 
expressions 4-13 
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t command (archiver) 8-3 
-t option (object format converter) 10-3 
Tektronix object format 10-1, 10-3 
.text (assembler directive) 5-45, 3-3, 
3-4, 5-4 

text section 3-3, 5-4, 5-45, 9-33, A-3 
.title (assembler directive) 5-46, 5-10 
TMS320C30 archiver 

See archiver 
TMS320C30 assembler 

See assembler 
TMS320C30 linker 

See linker 
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TMS320C30 object format converter 
See object format converter 
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-u option (linker) 9-10 
unconfigured memory 9-14, 9-27 
underflow (in expressions) 4-13 
uninitialized sections 3-2, 3-3, 5-17, 
5-47, 9-33 
holes 9-36 
initialization 9-36 
union definitions B-8 
unique labels for macros 7-9 
.usect (assembler directive) 5-47, 3-3, 


t 


.utag (assembler directive) B-1, B-8 
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v option (archiver) 8-3 
VAX/VMS software installation 2-3 
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well-defined expressions 4-13 
.width (assembler directive) 5-34, 5-10 
.word (assembler directive) 5-33, 5-6 
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x command (archiver) 8-3 

-x option (assembler) 4-3. 

-x option (object format converter) 10-3 
XDS emulator 1-3 
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Tucson (602) 292-2640. 


CALIFORNIA: Irvine (714) 660-1200; 
Roseville (916) 786-9208; 
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Raleigh (919) 876-2725. 
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PUERTO RICO: Hato Rey (809) 753-8700. 
TENNESSEE: Johnson City (615) 461-2192. 


TEXAS: Austin (512) 250-7655; 
Houston (713) 778-6592; 
Richardson (214) 680-5082; 
San Antonio (512) 496-1779. 
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WASHINGTON: Redmond (206) 881-3080. 
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Schweber (619) 450-0454; Wyle (619) 565-9171; 


San Francisco Bay Area: Arrow/Kierulff (408) 745-6600, 
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Hal!l-Mark (404) 447-8000; Marshall (404) 923-5750; 
Schweber (404) 449-9170. 


ILLINOIS: Arrow/Kierulff (312) 250-0500; 
Hall-Mark (312) 860-3800; Marshall (312) 490-0155; 
Newark (312) 784-5100; Schweber (312) 364-3750. 


INDIANA: Indianapolis: Arrow/Kierulff (317) 243-9353; 


Hall-Mark (317) 872-8875; Marshall (317) 297-0483; 
Schweber (317) 843-1050. 


IOWA: Arrow/Kierulff (319) 395-7230; 
Schweber (319) 373-1417. 


KANSAS: Kansas City: Arrow/Kierulff (913) 541-9542; 


Hall-Mark (913) 888-4747; Marshall (913) 492-3121; 
Schweber (913) 492-2922. 
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MARYLAND: Arrow/Kierulff (301) 995-6002; 
Hall-Mark (301) 988-9800; Marshall (301) 235-0464; 
Schweber (301) 840-5900; Zeus (301) 997-1118. 


MASSACHUSETTS Arrow/Kierulff (508) 658-0900; 
Hall-Mark (508) 667-0902; Marshall (508) 658-0810; 
Schweber (617) 275-5100; Time (617) 532-6200; 
Wyle (617) 273-7300; Zeus (617) 863-8800. 


MICHIGAN: Detrolt: Arrow/Kierulff (313) 462-2290; 
Hall-Mark ene 462-1205; Marshall : 13) 525-5850; 
Newark (313) 967-0600; Schwreber ( 13) 525-8100; 
Grand Rapids: Arrow/Klerultf (616) 243-0932. 


MINNESOTA: Arrow/Kierulff (612) 830-1800; 
Hall-Mark (612) 941-2600; Marshall (612) 559-2211; 
Schweber (612) 941-5280. 


MISSOURI: St. Louls: Arrow/Kierulff (314) 567-6888; 
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NEW HAMPSHIRE: Arrow/Kierulff (603) 668-6968; 
Schweber (603) 625-2250. 
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NEW YORK: Long Island: 
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(919) 725-8711; Hall-Mark (919) 872-0712; 
Marshall (919) 878-9882; Schweber (919) '876-0000. 
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(412) 963-6804. 
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Hall-Mark (512) 258-8848; Marshall (512) 837-1991; 
Schweber (512) 339-0088; Wyle (512) 834-9957; 
Dallas: Arrow/Kierulff (21 4) 380-6464 

Hall-Mark (214) 553-4300; Marshall (21 4) 233-5200; 
Schweber (214) 661- 501 0; Wyle (214) 235-9953; 
Zeus (214) 783-7010 

El Paso: Marshall (91 5) 593-0706; 

Houston: Arrow/Kierulff (713) 530-4700; 

Hall-Mark (713) 781-6100; Marshall (713) 895-9200; 
Schweber (713) 784-3600; Wyle (713) 879-9953. 


UTAH: Arrow/Kierulff (801) 973-6913; 
Hall-Mark (B01) 972-1008; Marshall (801) 485-1551; 
Wyle (801) 974-9953. 


WASHINGTON: Arrow/Kierulff (206) 575-4420; 
Marshall (206) 486-5747; Wyle (206) 881-1150. 


WISCONSIN: Arrow/Kierultf (414) 792-0150; 
Halt-Mark (414) 797-7844; Marshall (414) 797-8400; 
Schweber (414) 784-9020. 


CANADA: Calgary: Future (403) 235-5325; 
Edmonton: Future (403) 438-2858; 
Montreal: Arrow Canada (514) 735-5511; 
Future (514) 694-7710; 

Ottawa: Arrow Canada (613) 226-6903; 
Future (613) 820-831 

Quebec City: Arrow Canada (418) 871-7500; 
Toronto: Arrow Canada (416) 672-7769; 


_ Future (416) 638-4771; Marshall (416) 674-21 61; 


Vancouver: Arrow Canada (604) 291-2986; 
Future (604) 294-1166. 


Customer 
Response Center 


TOLL FREE: (800) 232-3200 


OUTSIDE USA: (214) 995-6611 
(8:00 a.m. — 5:00 p.m. CST) 


w% 
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